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

Subversion Repositories openrisc

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

Details | Compare with Previous | View Log

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

31
File: gdb.info,  Node: Automatic Overlay Debugging,  Next: Overlay Sample Program,  Prev: Overlay Commands,  Up: Overlays
32
 
33
11.3 Automatic Overlay Debugging
34
================================
35
 
36
GDB can automatically track which overlays are mapped and which are
37
not, given some simple co-operation from the overlay manager in the
38
inferior.  If you enable automatic overlay debugging with the `overlay
39
auto' command (*note Overlay Commands::), GDB looks in the inferior's
40
memory for certain variables describing the current state of the
41
overlays.
42
 
43
   Here are the variables your overlay manager must define to support
44
GDB's automatic overlay debugging:
45
 
46
`_ovly_table':
47
     This variable must be an array of the following structures:
48
 
49
          struct
50
          {
51
            /* The overlay's mapped address.  */
52
            unsigned long vma;
53
 
54
            /* The size of the overlay, in bytes.  */
55
            unsigned long size;
56
 
57
            /* The overlay's load address.  */
58
            unsigned long lma;
59
 
60
            /* Non-zero if the overlay is currently mapped;
61
               zero otherwise.  */
62
            unsigned long mapped;
63
          }
64
 
65
`_novlys':
66
     This variable must be a four-byte signed integer, holding the total
67
     number of elements in `_ovly_table'.
68
 
69
 
70
   To decide whether a particular overlay is mapped or not, GDB looks
71
for an entry in `_ovly_table' whose `vma' and `lma' members equal the
72
VMA and LMA of the overlay's section in the executable file.  When GDB
73
finds a matching entry, it consults the entry's `mapped' member to
74
determine whether the overlay is currently mapped.
75
 
76
   In addition, your overlay manager may define a function called
77
`_ovly_debug_event'.  If this function is defined, GDB will silently
78
set a breakpoint there.  If the overlay manager then calls this
79
function whenever it has changed the overlay table, this will enable
80
GDB to accurately keep track of which overlays are in program memory,
81
and update any breakpoints that may be set in overlays.  This will
82
allow breakpoints to work even if the overlays are kept in ROM or other
83
non-writable memory while they are not being executed.
84
 
85

86
File: gdb.info,  Node: Overlay Sample Program,  Prev: Automatic Overlay Debugging,  Up: Overlays
87
 
88
11.4 Overlay Sample Program
89
===========================
90
 
91
When linking a program which uses overlays, you must place the overlays
92
at their load addresses, while relocating them to run at their mapped
93
addresses.  To do this, you must write a linker script (*note Overlay
94
Description: (ld.info)Overlay Description.).  Unfortunately, since
95
linker scripts are specific to a particular host system, target
96
architecture, and target memory layout, this manual cannot provide
97
portable sample code demonstrating GDB's overlay support.
98
 
99
   However, the GDB source distribution does contain an overlaid
100
program, with linker scripts for a few systems, as part of its test
101
suite.  The program consists of the following files from
102
`gdb/testsuite/gdb.base':
103
 
104
`overlays.c'
105
     The main program file.
106
 
107
`ovlymgr.c'
108
     A simple overlay manager, used by `overlays.c'.
109
 
110
`foo.c'
111
`bar.c'
112
`baz.c'
113
`grbx.c'
114
     Overlay modules, loaded and used by `overlays.c'.
115
 
116
`d10v.ld'
117
`m32r.ld'
118
     Linker scripts for linking the test program on the `d10v-elf' and
119
     `m32r-elf' targets.
120
 
121
   You can build the test program using the `d10v-elf' GCC
122
cross-compiler like this:
123
 
124
     $ d10v-elf-gcc -g -c overlays.c
125
     $ d10v-elf-gcc -g -c ovlymgr.c
126
     $ d10v-elf-gcc -g -c foo.c
127
     $ d10v-elf-gcc -g -c bar.c
128
     $ d10v-elf-gcc -g -c baz.c
129
     $ d10v-elf-gcc -g -c grbx.c
130
     $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \
131
                       baz.o grbx.o -Wl,-Td10v.ld -o overlays
132
 
133
   The build process is identical for any other architecture, except
134
that you must substitute the appropriate compiler and linker script for
135
the target system for `d10v-elf-gcc' and `d10v.ld'.
136
 
137

138
File: gdb.info,  Node: Languages,  Next: Symbols,  Prev: Overlays,  Up: Top
139
 
140
12 Using GDB with Different Languages
141
*************************************
142
 
143
Although programming languages generally have common aspects, they are
144
rarely expressed in the same manner.  For instance, in ANSI C,
145
dereferencing a pointer `p' is accomplished by `*p', but in Modula-2,
146
it is accomplished by `p^'.  Values can also be represented (and
147
displayed) differently.  Hex numbers in C appear as `0x1ae', while in
148
Modula-2 they appear as `1AEH'.
149
 
150
   Language-specific information is built into GDB for some languages,
151
allowing you to express operations like the above in your program's
152
native language, and allowing GDB to output values in a manner
153
consistent with the syntax of your program's native language.  The
154
language you use to build expressions is called the "working language".
155
 
156
* Menu:
157
 
158
* Setting::                     Switching between source languages
159
* Show::                        Displaying the language
160
* Checks::                      Type and range checks
161
* Supported Languages::         Supported languages
162
* Unsupported Languages::       Unsupported languages
163
 
164

165
File: gdb.info,  Node: Setting,  Next: Show,  Up: Languages
166
 
167
12.1 Switching Between Source Languages
168
=======================================
169
 
170
There are two ways to control the working language--either have GDB set
171
it automatically, or select it manually yourself.  You can use the `set
172
language' command for either purpose.  On startup, GDB defaults to
173
setting the language automatically.  The working language is used to
174
determine how expressions you type are interpreted, how values are
175
printed, etc.
176
 
177
   In addition to the working language, every source file that GDB
178
knows about has its own working language.  For some object file
179
formats, the compiler might indicate which language a particular source
180
file is in.  However, most of the time GDB infers the language from the
181
name of the file.  The language of a source file controls whether C++
182
names are demangled--this way `backtrace' can show each frame
183
appropriately for its own language.  There is no way to set the
184
language of a source file from within GDB, but you can set the language
185
associated with a filename extension.  *Note Displaying the Language:
186
Show.
187
 
188
   This is most commonly a problem when you use a program, such as
189
`cfront' or `f2c', that generates C but is written in another language.
190
In that case, make the program use `#line' directives in its C output;
191
that way GDB will know the correct language of the source code of the
192
original program, and will display that source code, not the generated
193
C code.
194
 
195
* Menu:
196
 
197
* Filenames::                   Filename extensions and languages.
198
* Manually::                    Setting the working language manually
199
* Automatically::               Having GDB infer the source language
200
 
201

202
File: gdb.info,  Node: Filenames,  Next: Manually,  Up: Setting
203
 
204
12.1.1 List of Filename Extensions and Languages
205
------------------------------------------------
206
 
207
If a source file name ends in one of the following extensions, then GDB
208
infers that its language is the one indicated.
209
 
210
`.ada'
211
`.ads'
212
`.adb'
213
`.a'
214
     Ada source file.
215
 
216
`.c'
217
     C source file
218
 
219
`.C'
220
`.cc'
221
`.cp'
222
`.cpp'
223
`.cxx'
224
`.c++'
225
     C++ source file
226
 
227
`.m'
228
     Objective-C source file
229
 
230
`.f'
231
`.F'
232
     Fortran source file
233
 
234
`.mod'
235
     Modula-2 source file
236
 
237
`.s'
238
`.S'
239
     Assembler source file.  This actually behaves almost like C, but
240
     GDB does not skip over function prologues when stepping.
241
 
242
   In addition, you may set the language associated with a filename
243
extension.  *Note Displaying the Language: Show.
244
 
245

246
File: gdb.info,  Node: Manually,  Next: Automatically,  Prev: Filenames,  Up: Setting
247
 
248
12.1.2 Setting the Working Language
249
-----------------------------------
250
 
251
If you allow GDB to set the language automatically, expressions are
252
interpreted the same way in your debugging session and your program.
253
 
254
   If you wish, you may set the language manually.  To do this, issue
255
the command `set language LANG', where LANG is the name of a language,
256
such as `c' or `modula-2'.  For a list of the supported languages, type
257
`set language'.
258
 
259
   Setting the language manually prevents GDB from updating the working
260
language automatically.  This can lead to confusion if you try to debug
261
a program when the working language is not the same as the source
262
language, when an expression is acceptable to both languages--but means
263
different things.  For instance, if the current source file were
264
written in C, and GDB was parsing Modula-2, a command such as:
265
 
266
     print a = b + c
267
 
268
might not have the effect you intended.  In C, this means to add `b'
269
and `c' and place the result in `a'.  The result printed would be the
270
value of `a'.  In Modula-2, this means to compare `a' to the result of
271
`b+c', yielding a `BOOLEAN' value.
272
 
273

274
File: gdb.info,  Node: Automatically,  Prev: Manually,  Up: Setting
275
 
276
12.1.3 Having GDB Infer the Source Language
277
-------------------------------------------
278
 
279
To have GDB set the working language automatically, use `set language
280
local' or `set language auto'.  GDB then infers the working language.
281
That is, when your program stops in a frame (usually by encountering a
282
breakpoint), GDB sets the working language to the language recorded for
283
the function in that frame.  If the language for a frame is unknown
284
(that is, if the function or block corresponding to the frame was
285
defined in a source file that does not have a recognized extension),
286
the current working language is not changed, and GDB issues a warning.
287
 
288
   This may not seem necessary for most programs, which are written
289
entirely in one source language.  However, program modules and libraries
290
written in one source language can be used by a main program written in
291
a different source language.  Using `set language auto' in this case
292
frees you from having to set the working language manually.
293
 
294

295
File: gdb.info,  Node: Show,  Next: Checks,  Prev: Setting,  Up: Languages
296
 
297
12.2 Displaying the Language
298
============================
299
 
300
The following commands help you find out which language is the working
301
language, and also what language source files were written in.
302
 
303
`show language'
304
     Display the current working language.  This is the language you
305
     can use with commands such as `print' to build and compute
306
     expressions that may involve variables in your program.
307
 
308
`info frame'
309
     Display the source language for this frame.  This language becomes
310
     the working language if you use an identifier from this frame.
311
     *Note Information about a Frame: Frame Info, to identify the other
312
     information listed here.
313
 
314
`info source'
315
     Display the source language of this source file.  *Note Examining
316
     the Symbol Table: Symbols, to identify the other information
317
     listed here.
318
 
319
   In unusual circumstances, you may have source files with extensions
320
not in the standard list.  You can then set the extension associated
321
with a language explicitly:
322
 
323
`set extension-language EXT LANGUAGE'
324
     Tell GDB that source files with extension EXT are to be assumed as
325
     written in the source language LANGUAGE.
326
 
327
`info extensions'
328
     List all the filename extensions and the associated languages.
329
 
330

331
File: gdb.info,  Node: Checks,  Next: Supported Languages,  Prev: Show,  Up: Languages
332
 
333
12.3 Type and Range Checking
334
============================
335
 
336
     _Warning:_ In this release, the GDB commands for type and range
337
     checking are included, but they do not yet have any effect.  This
338
     section documents the intended facilities.
339
 
340
   Some languages are designed to guard you against making seemingly
341
common errors through a series of compile- and run-time checks.  These
342
include checking the type of arguments to functions and operators, and
343
making sure mathematical overflows are caught at run time.  Checks such
344
as these help to ensure a program's correctness once it has been
345
compiled by eliminating type mismatches, and providing active checks
346
for range errors when your program is running.
347
 
348
   GDB can check for conditions like the above if you wish.  Although
349
GDB does not check the statements in your program, it can check
350
expressions entered directly into GDB for evaluation via the `print'
351
command, for example.  As with the working language, GDB can also
352
decide whether or not to check automatically based on your program's
353
source language.  *Note Supported Languages: Supported Languages, for
354
the default settings of supported languages.
355
 
356
* Menu:
357
 
358
* Type Checking::               An overview of type checking
359
* Range Checking::              An overview of range checking
360
 
361

362
File: gdb.info,  Node: Type Checking,  Next: Range Checking,  Up: Checks
363
 
364
12.3.1 An Overview of Type Checking
365
-----------------------------------
366
 
367
Some languages, such as Modula-2, are strongly typed, meaning that the
368
arguments to operators and functions have to be of the correct type,
369
otherwise an error occurs.  These checks prevent type mismatch errors
370
from ever causing any run-time problems.  For example,
371
 
372
     1 + 2 => 3
373
but
374
     error--> 1 + 2.3
375
 
376
   The second example fails because the `CARDINAL' 1 is not
377
type-compatible with the `REAL' 2.3.
378
 
379
   For the expressions you use in GDB commands, you can tell the GDB
380
type checker to skip checking; to treat any mismatches as errors and
381
abandon the expression; or to only issue warnings when type mismatches
382
occur, but evaluate the expression anyway.  When you choose the last of
383
these, GDB evaluates expressions like the second example above, but
384
also issues a warning.
385
 
386
   Even if you turn type checking off, there may be other reasons
387
related to type that prevent GDB from evaluating an expression.  For
388
instance, GDB does not know how to add an `int' and a `struct foo'.
389
These particular type errors have nothing to do with the language in
390
use, and usually arise from expressions, such as the one described
391
above, which make little sense to evaluate anyway.
392
 
393
   Each language defines to what degree it is strict about type.  For
394
instance, both Modula-2 and C require the arguments to arithmetical
395
operators to be numbers.  In C, enumerated types and pointers can be
396
represented as numbers, so that they are valid arguments to mathematical
397
operators.  *Note Supported Languages: Supported Languages, for further
398
details on specific languages.
399
 
400
   GDB provides some additional commands for controlling the type
401
checker:
402
 
403
`set check type auto'
404
     Set type checking on or off based on the current working language.
405
     *Note Supported Languages: Supported Languages, for the default
406
     settings for each language.
407
 
408
`set check type on'
409
`set check type off'
410
     Set type checking on or off, overriding the default setting for the
411
     current working language.  Issue a warning if the setting does not
412
     match the language default.  If any type mismatches occur in
413
     evaluating an expression while type checking is on, GDB prints a
414
     message and aborts evaluation of the expression.
415
 
416
`set check type warn'
417
     Cause the type checker to issue warnings, but to always attempt to
418
     evaluate the expression.  Evaluating the expression may still be
419
     impossible for other reasons.  For example, GDB cannot add numbers
420
     and structures.
421
 
422
`show type'
423
     Show the current setting of the type checker, and whether or not
424
     GDB is setting it automatically.
425
 
426

427
File: gdb.info,  Node: Range Checking,  Prev: Type Checking,  Up: Checks
428
 
429
12.3.2 An Overview of Range Checking
430
------------------------------------
431
 
432
In some languages (such as Modula-2), it is an error to exceed the
433
bounds of a type; this is enforced with run-time checks.  Such range
434
checking is meant to ensure program correctness by making sure
435
computations do not overflow, or indices on an array element access do
436
not exceed the bounds of the array.
437
 
438
   For expressions you use in GDB commands, you can tell GDB to treat
439
range errors in one of three ways: ignore them, always treat them as
440
errors and abandon the expression, or issue warnings but evaluate the
441
expression anyway.
442
 
443
   A range error can result from numerical overflow, from exceeding an
444
array index bound, or when you type a constant that is not a member of
445
any type.  Some languages, however, do not treat overflows as an error.
446
In many implementations of C, mathematical overflow causes the result
447
to "wrap around" to lower values--for example, if M is the largest
448
integer value, and S is the smallest, then
449
 
450
     M + 1 => S
451
 
452
   This, too, is specific to individual languages, and in some cases
453
specific to individual compilers or machines.  *Note Supported
454
Languages: Supported Languages, for further details on specific
455
languages.
456
 
457
   GDB provides some additional commands for controlling the range
458
checker:
459
 
460
`set check range auto'
461
     Set range checking on or off based on the current working language.
462
     *Note Supported Languages: Supported Languages, for the default
463
     settings for each language.
464
 
465
`set check range on'
466
`set check range off'
467
     Set range checking on or off, overriding the default setting for
468
     the current working language.  A warning is issued if the setting
469
     does not match the language default.  If a range error occurs and
470
     range checking is on, then a message is printed and evaluation of
471
     the expression is aborted.
472
 
473
`set check range warn'
474
     Output messages when the GDB range checker detects a range error,
475
     but attempt to evaluate the expression anyway.  Evaluating the
476
     expression may still be impossible for other reasons, such as
477
     accessing memory that the process does not own (a typical example
478
     from many Unix systems).
479
 
480
`show range'
481
     Show the current setting of the range checker, and whether or not
482
     it is being set automatically by GDB.
483
 
484

485
File: gdb.info,  Node: Supported Languages,  Next: Unsupported Languages,  Prev: Checks,  Up: Languages
486
 
487
12.4 Supported Languages
488
========================
489
 
490
GDB supports C, C++, Objective-C, Fortran, Java, Pascal, assembly,
491
Modula-2, and Ada.  Some GDB features may be used in expressions
492
regardless of the language you use: the GDB `@' and `::' operators, and
493
the `{type}addr' construct (*note Expressions: Expressions.) can be
494
used with the constructs of any supported language.
495
 
496
   The following sections detail to what degree each source language is
497
supported by GDB.  These sections are not meant to be language
498
tutorials or references, but serve only as a reference guide to what the
499
GDB expression parser accepts, and what input and output formats should
500
look like for different languages.  There are many good books written
501
on each of these languages; please look to these for a language
502
reference or tutorial.
503
 
504
* Menu:
505
 
506
* C::                           C and C++
507
* Objective-C::                 Objective-C
508
* Fortran::                     Fortran
509
* Pascal::                      Pascal
510
* Modula-2::                    Modula-2
511
* Ada::                         Ada
512
 
513

514
File: gdb.info,  Node: C,  Next: Objective-C,  Up: Supported Languages
515
 
516
12.4.1 C and C++
517
----------------
518
 
519
Since C and C++ are so closely related, many features of GDB apply to
520
both languages.  Whenever this is the case, we discuss those languages
521
together.
522
 
523
   The C++ debugging facilities are jointly implemented by the C++
524
compiler and GDB.  Therefore, to debug your C++ code effectively, you
525
must compile your C++ programs with a supported C++ compiler, such as
526
GNU `g++', or the HP ANSI C++ compiler (`aCC').
527
 
528
   For best results when using GNU C++, use the DWARF 2 debugging
529
format; if it doesn't work on your system, try the stabs+ debugging
530
format.  You can select those formats explicitly with the `g++'
531
command-line options `-gdwarf-2' and `-gstabs+'.  *Note Options for
532
Debugging Your Program or GCC: (gcc.info)Debugging Options.
533
 
534
* Menu:
535
 
536
* C Operators::                 C and C++ operators
537
* C Constants::                 C and C++ constants
538
* C Plus Plus Expressions::     C++ expressions
539
* C Defaults::                  Default settings for C and C++
540
* C Checks::                    C and C++ type and range checks
541
* Debugging C::                 GDB and C
542
* Debugging C Plus Plus::       GDB features for C++
543
* Decimal Floating Point::      Numbers in Decimal Floating Point format
544
 
545

546
File: gdb.info,  Node: C Operators,  Next: C Constants,  Up: C
547
 
548
12.4.1.1 C and C++ Operators
549
............................
550
 
551
Operators must be defined on values of specific types.  For instance,
552
`+' is defined on numbers, but not on structures.  Operators are often
553
defined on groups of types.
554
 
555
   For the purposes of C and C++, the following definitions hold:
556
 
557
   * _Integral types_ include `int' with any of its storage-class
558
     specifiers; `char'; `enum'; and, for C++, `bool'.
559
 
560
   * _Floating-point types_ include `float', `double', and `long
561
     double' (if supported by the target platform).
562
 
563
   * _Pointer types_ include all types defined as `(TYPE *)'.
564
 
565
   * _Scalar types_ include all of the above.
566
 
567
 
568
The following operators are supported.  They are listed here in order
569
of increasing precedence:
570
 
571
`,'
572
     The comma or sequencing operator.  Expressions in a
573
     comma-separated list are evaluated from left to right, with the
574
     result of the entire expression being the last expression
575
     evaluated.
576
 
577
`='
578
     Assignment.  The value of an assignment expression is the value
579
     assigned.  Defined on scalar types.
580
 
581
`OP='
582
     Used in an expression of the form `A OP= B', and translated to
583
     `A = A OP B'.  `OP=' and `=' have the same precedence.  OP is any
584
     one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*',
585
     `/', `%'.
586
 
587
`?:'
588
     The ternary operator.  `A ? B : C' can be thought of as:  if A
589
     then B else C.  A should be of an integral type.
590
 
591
`||'
592
     Logical OR.  Defined on integral types.
593
 
594
`&&'
595
     Logical AND.  Defined on integral types.
596
 
597
`|'
598
     Bitwise OR.  Defined on integral types.
599
 
600
`^'
601
     Bitwise exclusive-OR.  Defined on integral types.
602
 
603
`&'
604
     Bitwise AND.  Defined on integral types.
605
 
606
`==, !='
607
     Equality and inequality.  Defined on scalar types.  The value of
608
     these expressions is 0 for false and non-zero for true.
609
 
610
`<, >, <=, >='
611
     Less than, greater than, less than or equal, greater than or equal.
612
     Defined on scalar types.  The value of these expressions is 0 for
613
     false and non-zero for true.
614
 
615
`<<, >>'
616
     left shift, and right shift.  Defined on integral types.
617
 
618
`@'
619
     The GDB "artificial array" operator (*note Expressions:
620
     Expressions.).
621
 
622
`+, -'
623
     Addition and subtraction.  Defined on integral types,
624
     floating-point types and pointer types.
625
 
626
`*, /, %'
627
     Multiplication, division, and modulus.  Multiplication and
628
     division are defined on integral and floating-point types.
629
     Modulus is defined on integral types.
630
 
631
`++, --'
632
     Increment and decrement.  When appearing before a variable, the
633
     operation is performed before the variable is used in an
634
     expression; when appearing after it, the variable's value is used
635
     before the operation takes place.
636
 
637
`*'
638
     Pointer dereferencing.  Defined on pointer types.  Same precedence
639
     as `++'.
640
 
641
`&'
642
     Address operator.  Defined on variables.  Same precedence as `++'.
643
 
644
     For debugging C++, GDB implements a use of `&' beyond what is
645
     allowed in the C++ language itself: you can use `&(&REF)' to
646
     examine the address where a C++ reference variable (declared with
647
     `&REF') is stored.
648
 
649
`-'
650
     Negative.  Defined on integral and floating-point types.  Same
651
     precedence as `++'.
652
 
653
`!'
654
     Logical negation.  Defined on integral types.  Same precedence as
655
     `++'.
656
 
657
`~'
658
     Bitwise complement operator.  Defined on integral types.  Same
659
     precedence as `++'.
660
 
661
`., ->'
662
     Structure member, and pointer-to-structure member.  For
663
     convenience, GDB regards the two as equivalent, choosing whether
664
     to dereference a pointer based on the stored type information.
665
     Defined on `struct' and `union' data.
666
 
667
`.*, ->*'
668
     Dereferences of pointers to members.
669
 
670
`[]'
671
     Array indexing.  `A[I]' is defined as `*(A+I)'.  Same precedence
672
     as `->'.
673
 
674
`()'
675
     Function parameter list.  Same precedence as `->'.
676
 
677
`::'
678
     C++ scope resolution operator.  Defined on `struct', `union', and
679
     `class' types.
680
 
681
`::'
682
     Doubled colons also represent the GDB scope operator (*note
683
     Expressions: Expressions.).  Same precedence as `::', above.
684
 
685
   If an operator is redefined in the user code, GDB usually attempts
686
to invoke the redefined version instead of using the operator's
687
predefined meaning.
688
 
689

690
File: gdb.info,  Node: C Constants,  Next: C Plus Plus Expressions,  Prev: C Operators,  Up: C
691
 
692
12.4.1.2 C and C++ Constants
693
............................
694
 
695
GDB allows you to express the constants of C and C++ in the following
696
ways:
697
 
698
   * Integer constants are a sequence of digits.  Octal constants are
699
     specified by a leading `0' (i.e. zero), and hexadecimal constants
700
     by a leading `0x' or `0X'.  Constants may also end with a letter
701
     `l', specifying that the constant should be treated as a `long'
702
     value.
703
 
704
   * Floating point constants are a sequence of digits, followed by a
705
     decimal point, followed by a sequence of digits, and optionally
706
     followed by an exponent.  An exponent is of the form:
707
     `e[[+]|-]NNN', where NNN is another sequence of digits.  The `+'
708
     is optional for positive exponents.  A floating-point constant may
709
     also end with a letter `f' or `F', specifying that the constant
710
     should be treated as being of the `float' (as opposed to the
711
     default `double') type; or with a letter `l' or `L', which
712
     specifies a `long double' constant.
713
 
714
   * Enumerated constants consist of enumerated identifiers, or their
715
     integral equivalents.
716
 
717
   * Character constants are a single character surrounded by single
718
     quotes (`''), or a number--the ordinal value of the corresponding
719
     character (usually its ASCII value).  Within quotes, the single
720
     character may be represented by a letter or by "escape sequences",
721
     which are of the form `\NNN', where NNN is the octal representation
722
     of the character's ordinal value; or of the form `\X', where `X'
723
     is a predefined special character--for example, `\n' for newline.
724
 
725
   * String constants are a sequence of character constants surrounded
726
     by double quotes (`"').  Any valid character constant (as described
727
     above) may appear.  Double quotes within the string must be
728
     preceded by a backslash, so for instance `"a\"b'c"' is a string of
729
     five characters.
730
 
731
   * Pointer constants are an integral value.  You can also write
732
     pointers to constants using the C operator `&'.
733
 
734
   * Array constants are comma-separated lists surrounded by braces `{'
735
     and `}'; for example, `{1,2,3}' is a three-element array of
736
     integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and
737
     `{&"hi", &"there", &"fred"}' is a three-element array of pointers.
738
 
739

740
File: gdb.info,  Node: C Plus Plus Expressions,  Next: C Defaults,  Prev: C Constants,  Up: C
741
 
742
12.4.1.3 C++ Expressions
743
........................
744
 
745
GDB expression handling can interpret most C++ expressions.
746
 
747
     _Warning:_ GDB can only debug C++ code if you use the proper
748
     compiler and the proper debug format.  Currently, GDB works best
749
     when debugging C++ code that is compiled with GCC 2.95.3 or with
750
     GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'.
751
     DWARF 2 is preferred over stabs+.  Most configurations of GCC emit
752
     either DWARF 2 or stabs+ as their default debug format, so you
753
     usually don't need to specify a debug format explicitly.  Other
754
     compilers and/or debug formats are likely to work badly or not at
755
     all when using GDB to debug C++ code.
756
 
757
  1. Member function calls are allowed; you can use expressions like
758
 
759
          count = aml->GetOriginal(x, y)
760
 
761
  2. While a member function is active (in the selected stack frame),
762
     your expressions have the same namespace available as the member
763
     function; that is, GDB allows implicit references to the class
764
     instance pointer `this' following the same rules as C++.
765
 
766
  3. You can call overloaded functions; GDB resolves the function call
767
     to the right definition, with some restrictions.  GDB does not
768
     perform overload resolution involving user-defined type
769
     conversions, calls to constructors, or instantiations of templates
770
     that do not exist in the program.  It also cannot handle ellipsis
771
     argument lists or default arguments.
772
 
773
     It does perform integral conversions and promotions, floating-point
774
     promotions, arithmetic conversions, pointer conversions,
775
     conversions of class objects to base classes, and standard
776
     conversions such as those of functions or arrays to pointers; it
777
     requires an exact match on the number of function arguments.
778
 
779
     Overload resolution is always performed, unless you have specified
780
     `set overload-resolution off'.  *Note GDB Features for C++:
781
     Debugging C Plus Plus.
782
 
783
     You must specify `set overload-resolution off' in order to use an
784
     explicit function signature to call an overloaded function, as in
785
          p 'foo(char,int)'('x', 13)
786
 
787
     The GDB command-completion facility can simplify this; see *Note
788
     Command Completion: Completion.
789
 
790
  4. GDB understands variables declared as C++ references; you can use
791
     them in expressions just as you do in C++ source--they are
792
     automatically dereferenced.
793
 
794
     In the parameter list shown when GDB displays a frame, the values
795
     of reference variables are not displayed (unlike other variables);
796
     this avoids clutter, since references are often used for large
797
     structures.  The _address_ of a reference variable is always
798
     shown, unless you have specified `set print address off'.
799
 
800
  5. GDB supports the C++ name resolution operator `::'--your
801
     expressions can use it just as expressions in your program do.
802
     Since one scope may be defined in another, you can use `::'
803
     repeatedly if necessary, for example in an expression like
804
     `SCOPE1::SCOPE2::NAME'.  GDB also allows resolving name scope by
805
     reference to source files, in both C and C++ debugging (*note
806
     Program Variables: Variables.).
807
 
808
   In addition, when used with HP's C++ compiler, GDB supports calling
809
virtual functions correctly, printing out virtual bases of objects,
810
calling functions in a base subobject, casting objects, and invoking
811
user-defined operators.
812
 
813

814
File: gdb.info,  Node: C Defaults,  Next: C Checks,  Prev: C Plus Plus Expressions,  Up: C
815
 
816
12.4.1.4 C and C++ Defaults
817
...........................
818
 
819
If you allow GDB to set type and range checking automatically, they
820
both default to `off' whenever the working language changes to C or
821
C++.  This happens regardless of whether you or GDB selects the working
822
language.
823
 
824
   If you allow GDB to set the language automatically, it recognizes
825
source files whose names end with `.c', `.C', or `.cc', etc, and when
826
GDB enters code compiled from one of these files, it sets the working
827
language to C or C++.  *Note Having GDB Infer the Source Language:
828
Automatically, for further details.
829
 
830

831
File: gdb.info,  Node: C Checks,  Next: Debugging C,  Prev: C Defaults,  Up: C
832
 
833
12.4.1.5 C and C++ Type and Range Checks
834
........................................
835
 
836
By default, when GDB parses C or C++ expressions, type checking is not
837
used.  However, if you turn type checking on, GDB considers two
838
variables type equivalent if:
839
 
840
   * The two variables are structured and have the same structure,
841
     union, or enumerated tag.
842
 
843
   * The two variables have the same type name, or types that have been
844
     declared equivalent through `typedef'.
845
 
846
 
847
   Range checking, if turned on, is done on mathematical operations.
848
Array indices are not checked, since they are often used to index a
849
pointer that is not itself an array.
850
 
851

852
File: gdb.info,  Node: Debugging C,  Next: Debugging C Plus Plus,  Prev: C Checks,  Up: C
853
 
854
12.4.1.6 GDB and C
855
..................
856
 
857
The `set print union' and `show print union' commands apply to the
858
`union' type.  When set to `on', any `union' that is inside a `struct'
859
or `class' is also printed.  Otherwise, it appears as `{...}'.
860
 
861
   The `@' operator aids in the debugging of dynamic arrays, formed
862
with pointers and a memory allocation function.  *Note Expressions:
863
Expressions.
864
 
865

866
File: gdb.info,  Node: Debugging C Plus Plus,  Next: Decimal Floating Point,  Prev: Debugging C,  Up: C
867
 
868
12.4.1.7 GDB Features for C++
869
.............................
870
 
871
Some GDB commands are particularly useful with C++, and some are
872
designed specifically for use with C++.  Here is a summary:
873
 
874
`breakpoint menus'
875
     When you want a breakpoint in a function whose name is overloaded,
876
     GDB breakpoint menus help you specify which function definition
877
     you want.  *Note Breakpoint Menus: Breakpoint Menus.
878
 
879
`rbreak REGEX'
880
     Setting breakpoints using regular expressions is helpful for
881
     setting breakpoints on overloaded functions that are not members
882
     of any special classes.  *Note Setting Breakpoints: Set Breaks.
883
 
884
`catch throw'
885
`catch catch'
886
     Debug C++ exception handling using these commands.  *Note Setting
887
     Catchpoints: Set Catchpoints.
888
 
889
`ptype TYPENAME'
890
     Print inheritance relationships as well as other information for
891
     type TYPENAME.  *Note Examining the Symbol Table: Symbols.
892
 
893
`set print demangle'
894
`show print demangle'
895
`set print asm-demangle'
896
`show print asm-demangle'
897
     Control whether C++ symbols display in their source form, both when
898
     displaying code as C++ source and when displaying disassemblies.
899
     *Note Print Settings: Print Settings.
900
 
901
`set print object'
902
`show print object'
903
     Choose whether to print derived (actual) or declared types of
904
     objects.  *Note Print Settings: Print Settings.
905
 
906
`set print vtbl'
907
`show print vtbl'
908
     Control the format for printing virtual function tables.  *Note
909
     Print Settings: Print Settings.  (The `vtbl' commands do not work
910
     on programs compiled with the HP ANSI C++ compiler (`aCC').)
911
 
912
`set overload-resolution on'
913
     Enable overload resolution for C++ expression evaluation.  The
914
     default is on.  For overloaded functions, GDB evaluates the
915
     arguments and searches for a function whose signature matches the
916
     argument types, using the standard C++ conversion rules (see *Note
917
     C++ Expressions: C Plus Plus Expressions, for details).  If it
918
     cannot find a match, it emits a message.
919
 
920
`set overload-resolution off'
921
     Disable overload resolution for C++ expression evaluation.  For
922
     overloaded functions that are not class member functions, GDB
923
     chooses the first function of the specified name that it finds in
924
     the symbol table, whether or not its arguments are of the correct
925
     type.  For overloaded functions that are class member functions,
926
     GDB searches for a function whose signature _exactly_ matches the
927
     argument types.
928
 
929
`show overload-resolution'
930
     Show the current setting of overload resolution.
931
 
932
`Overloaded symbol names'
933
     You can specify a particular definition of an overloaded symbol,
934
     using the same notation that is used to declare such symbols in
935
     C++: type `SYMBOL(TYPES)' rather than just SYMBOL.  You can also
936
     use the GDB command-line word completion facilities to list the
937
     available choices, or to finish the type list for you.  *Note
938
     Command Completion: Completion, for details on how to do this.
939
 
940

941
File: gdb.info,  Node: Decimal Floating Point,  Prev: Debugging C Plus Plus,  Up: C
942
 
943
12.4.1.8 Decimal Floating Point format
944
......................................
945
 
946
GDB can examine, set and perform computations with numbers in decimal
947
floating point format, which in the C language correspond to the
948
`_Decimal32', `_Decimal64' and `_Decimal128' types as specified by the
949
extension to support decimal floating-point arithmetic.
950
 
951
   There are two encodings in use, depending on the architecture: BID
952
(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed
953
Decimal) for PowerPC. GDB will use the appropriate encoding for the
954
configured target.
955
 
956
   Because of a limitation in `libdecnumber', the library used by GDB
957
to manipulate decimal floating point numbers, it is not possible to
958
convert (using a cast, for example) integers wider than 32-bit to
959
decimal float.
960
 
961
   In addition, in order to imitate GDB's behaviour with binary floating
962
point computations, error checking in decimal float operations ignores
963
underflow, overflow and divide by zero exceptions.
964
 
965
   In the PowerPC architecture, GDB provides a set of pseudo-registers
966
to inspect `_Decimal128' values stored in floating point registers. See
967
*Note PowerPC: PowerPC. for more details.
968
 
969

970
File: gdb.info,  Node: Objective-C,  Next: Fortran,  Prev: C,  Up: Supported Languages
971
 
972
12.4.2 Objective-C
973
------------------
974
 
975
This section provides information about some commands and command
976
options that are useful for debugging Objective-C code.  See also *Note
977
info classes: Symbols, and *Note info selectors: Symbols, for a few
978
more commands specific to Objective-C support.
979
 
980
* Menu:
981
 
982
* Method Names in Commands::
983
* The Print Command with Objective-C::
984
 
985

986
File: gdb.info,  Node: Method Names in Commands,  Next: The Print Command with Objective-C,  Up: Objective-C
987
 
988
12.4.2.1 Method Names in Commands
989
.................................
990
 
991
The following commands have been extended to accept Objective-C method
992
names as line specifications:
993
 
994
   * `clear'
995
 
996
   * `break'
997
 
998
   * `info line'
999
 
1000
   * `jump'
1001
 
1002
   * `list'
1003
 
1004
   A fully qualified Objective-C method name is specified as
1005
 
1006
     -[CLASS METHODNAME]
1007
 
1008
   where the minus sign is used to indicate an instance method and a
1009
plus sign (not shown) is used to indicate a class method.  The class
1010
name CLASS and method name METHODNAME are enclosed in brackets, similar
1011
to the way messages are specified in Objective-C source code.  For
1012
example, to set a breakpoint at the `create' instance method of class
1013
`Fruit' in the program currently being debugged, enter:
1014
 
1015
     break -[Fruit create]
1016
 
1017
   To list ten program lines around the `initialize' class method,
1018
enter:
1019
 
1020
     list +[NSText initialize]
1021
 
1022
   In the current version of GDB, the plus or minus sign is required.
1023
In future versions of GDB, the plus or minus sign will be optional, but
1024
you can use it to narrow the search.  It is also possible to specify
1025
just a method name:
1026
 
1027
     break create
1028
 
1029
   You must specify the complete method name, including any colons.  If
1030
your program's source files contain more than one `create' method,
1031
you'll be presented with a numbered list of classes that implement that
1032
method.  Indicate your choice by number, or type `0' to exit if none
1033
apply.
1034
 
1035
   As another example, to clear a breakpoint established at the
1036
`makeKeyAndOrderFront:' method of the `NSWindow' class, enter:
1037
 
1038
     clear -[NSWindow makeKeyAndOrderFront:]
1039
 
1040

1041
File: gdb.info,  Node: The Print Command with Objective-C,  Prev: Method Names in Commands,  Up: Objective-C
1042
 
1043
12.4.2.2 The Print Command With Objective-C
1044
...........................................
1045
 
1046
The print command has also been extended to accept methods.  For
1047
example:
1048
 
1049
     print -[OBJECT hash]
1050
 
1051
will tell GDB to send the `hash' message to OBJECT and print the
1052
result.  Also, an additional command has been added, `print-object' or
1053
`po' for short, which is meant to print the description of an object.
1054
However, this command may only work with certain Objective-C libraries
1055
that have a particular hook function, `_NSPrintForDebugger', defined.
1056
 
1057

1058
File: gdb.info,  Node: Fortran,  Next: Pascal,  Prev: Objective-C,  Up: Supported Languages
1059
 
1060
12.4.3 Fortran
1061
--------------
1062
 
1063
GDB can be used to debug programs written in Fortran, but it currently
1064
supports only the features of Fortran 77 language.
1065
 
1066
   Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers
1067
among them) append an underscore to the names of variables and
1068
functions.  When you debug programs compiled by those compilers, you
1069
will need to refer to variables and functions with a trailing
1070
underscore.
1071
 
1072
* Menu:
1073
 
1074
* Fortran Operators::           Fortran operators and expressions
1075
* Fortran Defaults::            Default settings for Fortran
1076
* Special Fortran Commands::    Special GDB commands for Fortran
1077
 
1078

1079
File: gdb.info,  Node: Fortran Operators,  Next: Fortran Defaults,  Up: Fortran
1080
 
1081
12.4.3.1 Fortran Operators and Expressions
1082
..........................................
1083
 
1084
Operators must be defined on values of specific types.  For instance,
1085
`+' is defined on numbers, but not on characters or other non-
1086
arithmetic types.  Operators are often defined on groups of types.
1087
 
1088
`**'
1089
     The exponentiation operator. It raises the first operand to the
1090
     power of the second one.
1091
 
1092
`:'
1093
     The range operator.  Normally used in the form of array(low:high)
1094
     to represent a section of array.
1095
 
1096

1097
File: gdb.info,  Node: Fortran Defaults,  Next: Special Fortran Commands,  Prev: Fortran Operators,  Up: Fortran
1098
 
1099
12.4.3.2 Fortran Defaults
1100
.........................
1101
 
1102
Fortran symbols are usually case-insensitive, so GDB by default uses
1103
case-insensitive matches for Fortran symbols.  You can change that with
1104
the `set case-insensitive' command, see *Note Symbols::, for the
1105
details.
1106
 
1107

1108
File: gdb.info,  Node: Special Fortran Commands,  Prev: Fortran Defaults,  Up: Fortran
1109
 
1110
12.4.3.3 Special Fortran Commands
1111
.................................
1112
 
1113
GDB has some commands to support Fortran-specific features, such as
1114
displaying common blocks.
1115
 
1116
`info common [COMMON-NAME]'
1117
     This command prints the values contained in the Fortran `COMMON'
1118
     block whose name is COMMON-NAME.  With no argument, the names of
1119
     all `COMMON' blocks visible at the current program location are
1120
     printed.
1121
 
1122

1123
File: gdb.info,  Node: Pascal,  Next: Modula-2,  Prev: Fortran,  Up: Supported Languages
1124
 
1125
12.4.4 Pascal
1126
-------------
1127
 
1128
Debugging Pascal programs which use sets, subranges, file variables, or
1129
nested functions does not currently work.  GDB does not support
1130
entering expressions, printing values, or similar features using Pascal
1131
syntax.
1132
 
1133
   The Pascal-specific command `set print pascal_static-members'
1134
controls whether static members of Pascal objects are displayed.  *Note
1135
pascal_static-members: Print Settings.
1136
 
1137

1138
File: gdb.info,  Node: Modula-2,  Next: Ada,  Prev: Pascal,  Up: Supported Languages
1139
 
1140
12.4.5 Modula-2
1141
---------------
1142
 
1143
The extensions made to GDB to support Modula-2 only support output from
1144
the GNU Modula-2 compiler (which is currently being developed).  Other
1145
Modula-2 compilers are not currently supported, and attempting to debug
1146
executables produced by them is most likely to give an error as GDB
1147
reads in the executable's symbol table.
1148
 
1149
* Menu:
1150
 
1151
* M2 Operators::                Built-in operators
1152
* Built-In Func/Proc::          Built-in functions and procedures
1153
* M2 Constants::                Modula-2 constants
1154
* M2 Types::                    Modula-2 types
1155
* M2 Defaults::                 Default settings for Modula-2
1156
* Deviations::                  Deviations from standard Modula-2
1157
* M2 Checks::                   Modula-2 type and range checks
1158
* M2 Scope::                    The scope operators `::' and `.'
1159
* GDB/M2::                      GDB and Modula-2
1160
 
1161

1162
File: gdb.info,  Node: M2 Operators,  Next: Built-In Func/Proc,  Up: Modula-2
1163
 
1164
12.4.5.1 Operators
1165
..................
1166
 
1167
Operators must be defined on values of specific types.  For instance,
1168
`+' is defined on numbers, but not on structures.  Operators are often
1169
defined on groups of types.  For the purposes of Modula-2, the
1170
following definitions hold:
1171
 
1172
   * _Integral types_ consist of `INTEGER', `CARDINAL', and their
1173
     subranges.
1174
 
1175
   * _Character types_ consist of `CHAR' and its subranges.
1176
 
1177
   * _Floating-point types_ consist of `REAL'.
1178
 
1179
   * _Pointer types_ consist of anything declared as `POINTER TO TYPE'.
1180
 
1181
   * _Scalar types_ consist of all of the above.
1182
 
1183
   * _Set types_ consist of `SET' and `BITSET' types.
1184
 
1185
   * _Boolean types_ consist of `BOOLEAN'.
1186
 
1187
The following operators are supported, and appear in order of
1188
increasing precedence:
1189
 
1190
`,'
1191
     Function argument or array index separator.
1192
 
1193
`:='
1194
     Assignment.  The value of VAR `:=' VALUE is VALUE.
1195
 
1196
`<, >'
1197
     Less than, greater than on integral, floating-point, or enumerated
1198
     types.
1199
 
1200
`<=, >='
1201
     Less than or equal to, greater than or equal to on integral,
1202
     floating-point and enumerated types, or set inclusion on set
1203
     types.  Same precedence as `<'.
1204
 
1205
`=, <>, #'
1206
     Equality and two ways of expressing inequality, valid on scalar
1207
     types.  Same precedence as `<'.  In GDB scripts, only `<>' is
1208
     available for inequality, since `#' conflicts with the script
1209
     comment character.
1210
 
1211
`IN'
1212
     Set membership.  Defined on set types and the types of their
1213
     members.  Same precedence as `<'.
1214
 
1215
`OR'
1216
     Boolean disjunction.  Defined on boolean types.
1217
 
1218
`AND, &'
1219
     Boolean conjunction.  Defined on boolean types.
1220
 
1221
`@'
1222
     The GDB "artificial array" operator (*note Expressions:
1223
     Expressions.).
1224
 
1225
`+, -'
1226
     Addition and subtraction on integral and floating-point types, or
1227
     union and difference on set types.
1228
 
1229
`*'
1230
     Multiplication on integral and floating-point types, or set
1231
     intersection on set types.
1232
 
1233
`/'
1234
     Division on floating-point types, or symmetric set difference on
1235
     set types.  Same precedence as `*'.
1236
 
1237
`DIV, MOD'
1238
     Integer division and remainder.  Defined on integral types.  Same
1239
     precedence as `*'.
1240
 
1241
`-'
1242
     Negative. Defined on `INTEGER' and `REAL' data.
1243
 
1244
`^'
1245
     Pointer dereferencing.  Defined on pointer types.
1246
 
1247
`NOT'
1248
     Boolean negation.  Defined on boolean types.  Same precedence as
1249
     `^'.
1250
 
1251
`.'
1252
     `RECORD' field selector.  Defined on `RECORD' data.  Same
1253
     precedence as `^'.
1254
 
1255
`[]'
1256
     Array indexing.  Defined on `ARRAY' data.  Same precedence as `^'.
1257
 
1258
`()'
1259
     Procedure argument list.  Defined on `PROCEDURE' objects.  Same
1260
     precedence as `^'.
1261
 
1262
`::, .'
1263
     GDB and Modula-2 scope operators.
1264
 
1265
     _Warning:_ Set expressions and their operations are not yet
1266
     supported, so GDB treats the use of the operator `IN', or the use
1267
     of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>='
1268
     on sets as an error.
1269
 
1270

1271
File: gdb.info,  Node: Built-In Func/Proc,  Next: M2 Constants,  Prev: M2 Operators,  Up: Modula-2
1272
 
1273
12.4.5.2 Built-in Functions and Procedures
1274
..........................................
1275
 
1276
Modula-2 also makes available several built-in procedures and functions.
1277
In describing these, the following metavariables are used:
1278
 
1279
A
1280
     represents an `ARRAY' variable.
1281
 
1282
C
1283
     represents a `CHAR' constant or variable.
1284
 
1285
I
1286
     represents a variable or constant of integral type.
1287
 
1288
M
1289
     represents an identifier that belongs to a set.  Generally used in
1290
     the same function with the metavariable S.  The type of S should
1291
     be `SET OF MTYPE' (where MTYPE is the type of M).
1292
 
1293
N
1294
     represents a variable or constant of integral or floating-point
1295
     type.
1296
 
1297
R
1298
     represents a variable or constant of floating-point type.
1299
 
1300
T
1301
     represents a type.
1302
 
1303
V
1304
     represents a variable.
1305
 
1306
X
1307
     represents a variable or constant of one of many types.  See the
1308
     explanation of the function for details.
1309
 
1310
   All Modula-2 built-in procedures also return a result, described
1311
below.
1312
 
1313
`ABS(N)'
1314
     Returns the absolute value of N.
1315
 
1316
`CAP(C)'
1317
     If C is a lower case letter, it returns its upper case equivalent,
1318
     otherwise it returns its argument.
1319
 
1320
`CHR(I)'
1321
     Returns the character whose ordinal value is I.
1322
 
1323
`DEC(V)'
1324
     Decrements the value in the variable V by one.  Returns the new
1325
     value.
1326
 
1327
`DEC(V,I)'
1328
     Decrements the value in the variable V by I.  Returns the new
1329
     value.
1330
 
1331
`EXCL(M,S)'
1332
     Removes the element M from the set S.  Returns the new set.
1333
 
1334
`FLOAT(I)'
1335
     Returns the floating point equivalent of the integer I.
1336
 
1337
`HIGH(A)'
1338
     Returns the index of the last member of A.
1339
 
1340
`INC(V)'
1341
     Increments the value in the variable V by one.  Returns the new
1342
     value.
1343
 
1344
`INC(V,I)'
1345
     Increments the value in the variable V by I.  Returns the new
1346
     value.
1347
 
1348
`INCL(M,S)'
1349
     Adds the element M to the set S if it is not already there.
1350
     Returns the new set.
1351
 
1352
`MAX(T)'
1353
     Returns the maximum value of the type T.
1354
 
1355
`MIN(T)'
1356
     Returns the minimum value of the type T.
1357
 
1358
`ODD(I)'
1359
     Returns boolean TRUE if I is an odd number.
1360
 
1361
`ORD(X)'
1362
     Returns the ordinal value of its argument.  For example, the
1363
     ordinal value of a character is its ASCII value (on machines
1364
     supporting the ASCII character set).  X must be of an ordered
1365
     type, which include integral, character and enumerated types.
1366
 
1367
`SIZE(X)'
1368
     Returns the size of its argument.  X can be a variable or a type.
1369
 
1370
`TRUNC(R)'
1371
     Returns the integral part of R.
1372
 
1373
`TSIZE(X)'
1374
     Returns the size of its argument.  X can be a variable or a type.
1375
 
1376
`VAL(T,I)'
1377
     Returns the member of the type T whose ordinal value is I.
1378
 
1379
     _Warning:_  Sets and their operations are not yet supported, so
1380
     GDB treats the use of procedures `INCL' and `EXCL' as an error.
1381
 
1382

1383
File: gdb.info,  Node: M2 Constants,  Next: M2 Types,  Prev: Built-In Func/Proc,  Up: Modula-2
1384
 
1385
12.4.5.3 Constants
1386
..................
1387
 
1388
GDB allows you to express the constants of Modula-2 in the following
1389
ways:
1390
 
1391
   * Integer constants are simply a sequence of digits.  When used in an
1392
     expression, a constant is interpreted to be type-compatible with
1393
     the rest of the expression.  Hexadecimal integers are specified by
1394
     a trailing `H', and octal integers by a trailing `B'.
1395
 
1396
   * Floating point constants appear as a sequence of digits, followed
1397
     by a decimal point and another sequence of digits.  An optional
1398
     exponent can then be specified, in the form `E[+|-]NNN', where
1399
     `[+|-]NNN' is the desired exponent.  All of the digits of the
1400
     floating point constant must be valid decimal (base 10) digits.
1401
 
1402
   * Character constants consist of a single character enclosed by a
1403
     pair of like quotes, either single (`'') or double (`"').  They may
1404
     also be expressed by their ordinal value (their ASCII value,
1405
     usually) followed by a `C'.
1406
 
1407
   * String constants consist of a sequence of characters enclosed by a
1408
     pair of like quotes, either single (`'') or double (`"').  Escape
1409
     sequences in the style of C are also allowed.  *Note C and C++
1410
     Constants: C Constants, for a brief explanation of escape
1411
     sequences.
1412
 
1413
   * Enumerated constants consist of an enumerated identifier.
1414
 
1415
   * Boolean constants consist of the identifiers `TRUE' and `FALSE'.
1416
 
1417
   * Pointer constants consist of integral values only.
1418
 
1419
   * Set constants are not yet supported.
1420
 
1421

1422
File: gdb.info,  Node: M2 Types,  Next: M2 Defaults,  Prev: M2 Constants,  Up: Modula-2
1423
 
1424
12.4.5.4 Modula-2 Types
1425
.......................
1426
 
1427
Currently GDB can print the following data types in Modula-2 syntax:
1428
array types, record types, set types, pointer types, procedure types,
1429
enumerated types, subrange types and base types.  You can also print
1430
the contents of variables declared using these type.  This section
1431
gives a number of simple source code examples together with sample GDB
1432
sessions.
1433
 
1434
   The first example contains the following section of code:
1435
 
1436
     VAR
1437
        s: SET OF CHAR ;
1438
        r: [20..40] ;
1439
 
1440
and you can request GDB to interrogate the type and value of `r' and
1441
`s'.
1442
 
1443
     (gdb) print s
1444
     {'A'..'C', 'Z'}
1445
     (gdb) ptype s
1446
     SET OF CHAR
1447
     (gdb) print r
1448
     21
1449
     (gdb) ptype r
1450
     [20..40]
1451
 
1452
Likewise if your source code declares `s' as:
1453
 
1454
     VAR
1455
        s: SET ['A'..'Z'] ;
1456
 
1457
then you may query the type of `s' by:
1458
 
1459
     (gdb) ptype s
1460
     type = SET ['A'..'Z']
1461
 
1462
Note that at present you cannot interactively manipulate set
1463
expressions using the debugger.
1464
 
1465
   The following example shows how you might declare an array in
1466
Modula-2 and how you can interact with GDB to print its type and
1467
contents:
1468
 
1469
     VAR
1470
        s: ARRAY [-10..10] OF CHAR ;
1471
 
1472
     (gdb) ptype s
1473
     ARRAY [-10..10] OF CHAR
1474
 
1475
   Note that the array handling is not yet complete and although the
1476
type is printed correctly, expression handling still assumes that all
1477
arrays have a lower bound of zero and not `-10' as in the example above.
1478
 
1479
   Here are some more type related Modula-2 examples:
1480
 
1481
     TYPE
1482
        colour = (blue, red, yellow, green) ;
1483
        t = [blue..yellow] ;
1484
     VAR
1485
        s: t ;
1486
     BEGIN
1487
        s := blue ;
1488
 
1489
The GDB interaction shows how you can query the data type and value of
1490
a variable.
1491
 
1492
     (gdb) print s
1493
     $1 = blue
1494
     (gdb) ptype t
1495
     type = [blue..yellow]
1496
 
1497
In this example a Modula-2 array is declared and its contents
1498
displayed.  Observe that the contents are written in the same way as
1499
their `C' counterparts.
1500
 
1501
     VAR
1502
        s: ARRAY [1..5] OF CARDINAL ;
1503
     BEGIN
1504
        s[1] := 1 ;
1505
 
1506
     (gdb) print s
1507
     $1 = {1, 0, 0, 0, 0}
1508
     (gdb) ptype s
1509
     type = ARRAY [1..5] OF CARDINAL
1510
 
1511
   The Modula-2 language interface to GDB also understands pointer
1512
types as shown in this example:
1513
 
1514
     VAR
1515
        s: POINTER TO ARRAY [1..5] OF CARDINAL ;
1516
     BEGIN
1517
        NEW(s) ;
1518
        s^[1] := 1 ;
1519
 
1520
and you can request that GDB describes the type of `s'.
1521
 
1522
     (gdb) ptype s
1523
     type = POINTER TO ARRAY [1..5] OF CARDINAL
1524
 
1525
   GDB handles compound types as we can see in this example.  Here we
1526
combine array types, record types, pointer types and subrange types:
1527
 
1528
     TYPE
1529
        foo = RECORD
1530
                 f1: CARDINAL ;
1531
                 f2: CHAR ;
1532
                 f3: myarray ;
1533
              END ;
1534
 
1535
        myarray = ARRAY myrange OF CARDINAL ;
1536
        myrange = [-2..2] ;
1537
     VAR
1538
        s: POINTER TO ARRAY myrange OF foo ;
1539
 
1540
and you can ask GDB to describe the type of `s' as shown below.
1541
 
1542
     (gdb) ptype s
1543
     type = POINTER TO ARRAY [-2..2] OF foo = RECORD
1544
         f1 : CARDINAL;
1545
         f2 : CHAR;
1546
         f3 : ARRAY [-2..2] OF CARDINAL;
1547
     END
1548
 
1549

1550
File: gdb.info,  Node: M2 Defaults,  Next: Deviations,  Prev: M2 Types,  Up: Modula-2
1551
 
1552
12.4.5.5 Modula-2 Defaults
1553
..........................
1554
 
1555
If type and range checking are set automatically by GDB, they both
1556
default to `on' whenever the working language changes to Modula-2.
1557
This happens regardless of whether you or GDB selected the working
1558
language.
1559
 
1560
   If you allow GDB to set the language automatically, then entering
1561
code compiled from a file whose name ends with `.mod' sets the working
1562
language to Modula-2.  *Note Having GDB Infer the Source Language:
1563
Automatically, for further details.
1564
 
1565

1566
File: gdb.info,  Node: Deviations,  Next: M2 Checks,  Prev: M2 Defaults,  Up: Modula-2
1567
 
1568
12.4.5.6 Deviations from Standard Modula-2
1569
..........................................
1570
 
1571
A few changes have been made to make Modula-2 programs easier to debug.
1572
This is done primarily via loosening its type strictness:
1573
 
1574
   * Unlike in standard Modula-2, pointer constants can be formed by
1575
     integers.  This allows you to modify pointer variables during
1576
     debugging.  (In standard Modula-2, the actual address contained in
1577
     a pointer variable is hidden from you; it can only be modified
1578
     through direct assignment to another pointer variable or
1579
     expression that returned a pointer.)
1580
 
1581
   * C escape sequences can be used in strings and characters to
1582
     represent non-printable characters.  GDB prints out strings with
1583
     these escape sequences embedded.  Single non-printable characters
1584
     are printed using the `CHR(NNN)' format.
1585
 
1586
   * The assignment operator (`:=') returns the value of its right-hand
1587
     argument.
1588
 
1589
   * All built-in procedures both modify _and_ return their argument.
1590
 
1591

1592
File: gdb.info,  Node: M2 Checks,  Next: M2 Scope,  Prev: Deviations,  Up: Modula-2
1593
 
1594
12.4.5.7 Modula-2 Type and Range Checks
1595
.......................................
1596
 
1597
     _Warning:_ in this release, GDB does not yet perform type or range
1598
     checking.
1599
 
1600
   GDB considers two Modula-2 variables type equivalent if:
1601
 
1602
   * They are of types that have been declared equivalent via a `TYPE
1603
     T1 = T2' statement
1604
 
1605
   * They have been declared on the same line.  (Note:  This is true of
1606
     the GNU Modula-2 compiler, but it may not be true of other
1607
     compilers.)
1608
 
1609
   As long as type checking is enabled, any attempt to combine variables
1610
whose types are not equivalent is an error.
1611
 
1612
   Range checking is done on all mathematical operations, assignment,
1613
array index bounds, and all built-in functions and procedures.
1614
 
1615

1616
File: gdb.info,  Node: M2 Scope,  Next: GDB/M2,  Prev: M2 Checks,  Up: Modula-2
1617
 
1618
12.4.5.8 The Scope Operators `::' and `.'
1619
.........................................
1620
 
1621
There are a few subtle differences between the Modula-2 scope operator
1622
(`.') and the GDB scope operator (`::').  The two have similar syntax:
1623
 
1624
 
1625
     MODULE . ID
1626
     SCOPE :: ID
1627
 
1628
where SCOPE is the name of a module or a procedure, MODULE the name of
1629
a module, and ID is any declared identifier within your program, except
1630
another module.
1631
 
1632
   Using the `::' operator makes GDB search the scope specified by
1633
SCOPE for the identifier ID.  If it is not found in the specified
1634
scope, then GDB searches all scopes enclosing the one specified by
1635
SCOPE.
1636
 
1637
   Using the `.' operator makes GDB search the current scope for the
1638
identifier specified by ID that was imported from the definition module
1639
specified by MODULE.  With this operator, it is an error if the
1640
identifier ID was not imported from definition module MODULE, or if ID
1641
is not an identifier in MODULE.
1642
 
1643

1644
File: gdb.info,  Node: GDB/M2,  Prev: M2 Scope,  Up: Modula-2
1645
 
1646
12.4.5.9 GDB and Modula-2
1647
.........................
1648
 
1649
Some GDB commands have little use when debugging Modula-2 programs.
1650
Five subcommands of `set print' and `show print' apply specifically to
1651
C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'.
1652
The first four apply to C++, and the last to the C `union' type, which
1653
has no direct analogue in Modula-2.
1654
 
1655
   The `@' operator (*note Expressions: Expressions.), while available
1656
with any language, is not useful with Modula-2.  Its intent is to aid
1657
the debugging of "dynamic arrays", which cannot be created in Modula-2
1658
as they can in C or C++.  However, because an address can be specified
1659
by an integral constant, the construct `{TYPE}ADREXP' is still useful.
1660
 
1661
   In GDB scripts, the Modula-2 inequality operator `#' is interpreted
1662
as the beginning of a comment.  Use `<>' instead.
1663
 
1664

1665
File: gdb.info,  Node: Ada,  Prev: Modula-2,  Up: Supported Languages
1666
 
1667
12.4.6 Ada
1668
----------
1669
 
1670
The extensions made to GDB for Ada only support output from the GNU Ada
1671
(GNAT) compiler.  Other Ada compilers are not currently supported, and
1672
attempting to debug executables produced by them is most likely to be
1673
difficult.
1674
 
1675
* Menu:
1676
 
1677
* Ada Mode Intro::              General remarks on the Ada syntax
1678
                                   and semantics supported by Ada mode
1679
                                   in GDB.
1680
* Omissions from Ada::          Restrictions on the Ada expression syntax.
1681
* Additions to Ada::            Extensions of the Ada expression syntax.
1682
* Stopping Before Main Program:: Debugging the program during elaboration.
1683
* Ada Glitches::                Known peculiarities of Ada mode.
1684
 
1685

1686
File: gdb.info,  Node: Ada Mode Intro,  Next: Omissions from Ada,  Up: Ada
1687
 
1688
12.4.6.1 Introduction
1689
.....................
1690
 
1691
The Ada mode of GDB supports a fairly large subset of Ada expression
1692
syntax, with some extensions.  The philosophy behind the design of this
1693
subset is
1694
 
1695
   * That GDB should provide basic literals and access to operations for
1696
     arithmetic, dereferencing, field selection, indexing, and
1697
     subprogram calls, leaving more sophisticated computations to
1698
     subprograms written into the program (which therefore may be
1699
     called from GDB).
1700
 
1701
   * That type safety and strict adherence to Ada language restrictions
1702
     are not particularly important to the GDB user.
1703
 
1704
   * That brevity is important to the GDB user.
1705
 
1706
   Thus, for brevity, the debugger acts as if there were implicit
1707
`with' and `use' clauses in effect for all user-written packages,
1708
making it unnecessary to fully qualify most names with their packages,
1709
regardless of context.  Where this causes ambiguity, GDB asks the
1710
user's intent.
1711
 
1712
   The debugger will start in Ada mode if it detects an Ada main
1713
program.  As for other languages, it will enter Ada mode when stopped
1714
in a program that was translated from an Ada source file.
1715
 
1716
   While in Ada mode, you may use `-' for comments.  This is useful
1717
mostly for documenting command files.  The standard GDB comment (`#')
1718
still works at the beginning of a line in Ada mode, but not in the
1719
middle (to allow based literals).
1720
 
1721
   The debugger supports limited overloading.  Given a subprogram call
1722
in which the function symbol has multiple definitions, it will use the
1723
number of actual parameters and some information about their types to
1724
attempt to narrow the set of definitions.  It also makes very limited
1725
use of context, preferring procedures to functions in the context of
1726
the `call' command, and functions to procedures elsewhere.
1727
 
1728

1729
File: gdb.info,  Node: Omissions from Ada,  Next: Additions to Ada,  Prev: Ada Mode Intro,  Up: Ada
1730
 
1731
12.4.6.2 Omissions from Ada
1732
...........................
1733
 
1734
Here are the notable omissions from the subset:
1735
 
1736
   * Only a subset of the attributes are supported:
1737
 
1738
        - 'First, 'Last, and 'Length  on array objects (not on types
1739
          and subtypes).
1740
 
1741
        - 'Min and 'Max.
1742
 
1743
        - 'Pos and 'Val.
1744
 
1745
        - 'Tag.
1746
 
1747
        - 'Range on array objects (not subtypes), but only as the right
1748
          operand of the membership (`in') operator.
1749
 
1750
        - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT
1751
          extension).
1752
 
1753
        - 'Address.
1754
 
1755
   * The names in `Characters.Latin_1' are not available and
1756
     concatenation is not implemented.  Thus, escape characters in
1757
     strings are not currently available.
1758
 
1759
   * Equality tests (`=' and `/=') on arrays test for bitwise equality
1760
     of representations.  They will generally work correctly for
1761
     strings and arrays whose elements have integer or enumeration
1762
     types.  They may not work correctly for arrays whose element types
1763
     have user-defined equality, for arrays of real values (in
1764
     particular, IEEE-conformant floating point, because of negative
1765
     zeroes and NaNs), and for arrays whose elements contain unused
1766
     bits with indeterminate values.
1767
 
1768
   * The other component-by-component array operations (`and', `or',
1769
     `xor', `not', and relational tests other than equality) are not
1770
     implemented.
1771
 
1772
   * There is limited support for array and record aggregates.  They are
1773
     permitted only on the right sides of assignments, as in these
1774
     examples:
1775
 
1776
          set An_Array := (1, 2, 3, 4, 5, 6)
1777
          set An_Array := (1, others => 0)
1778
          set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6)
1779
          set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9))
1780
          set A_Record := (1, "Peter", True);
1781
          set A_Record := (Name => "Peter", Id => 1, Alive => True)
1782
 
1783
     Changing a discriminant's value by assigning an aggregate has an
1784
     undefined effect if that discriminant is used within the record.
1785
     However, you can first modify discriminants by directly assigning
1786
     to them (which normally would not be allowed in Ada), and then
1787
     performing an aggregate assignment.  For example, given a variable
1788
     `A_Rec' declared to have a type such as:
1789
 
1790
          type Rec (Len : Small_Integer := 0) is record
1791
              Id : Integer;
1792
              Vals : IntArray (1 .. Len);
1793
          end record;
1794
 
1795
     you can assign a value with a different size of `Vals' with two
1796
     assignments:
1797
 
1798
          set A_Rec.Len := 4
1799
          set A_Rec := (Id => 42, Vals => (1, 2, 3, 4))
1800
 
1801
     As this example also illustrates, GDB is very loose about the usual
1802
     rules concerning aggregates.  You may leave out some of the
1803
     components of an array or record aggregate (such as the `Len'
1804
     component in the assignment to `A_Rec' above); they will retain
1805
     their original values upon assignment.  You may freely use dynamic
1806
     values as indices in component associations.  You may even use
1807
     overlapping or redundant component associations, although which
1808
     component values are assigned in such cases is not defined.
1809
 
1810
   * Calls to dispatching subprograms are not implemented.
1811
 
1812
   * The overloading algorithm is much more limited (i.e., less
1813
     selective) than that of real Ada.  It makes only limited use of
1814
     the context in which a subexpression appears to resolve its
1815
     meaning, and it is much looser in its rules for allowing type
1816
     matches.  As a result, some function calls will be ambiguous, and
1817
     the user will be asked to choose the proper resolution.
1818
 
1819
   * The `new' operator is not implemented.
1820
 
1821
   * Entry calls are not implemented.
1822
 
1823
   * Aside from printing, arithmetic operations on the native VAX
1824
     floating-point formats are not supported.
1825
 
1826
   * It is not possible to slice a packed array.
1827
 
1828

1829
File: gdb.info,  Node: Additions to Ada,  Next: Stopping Before Main Program,  Prev: Omissions from Ada,  Up: Ada
1830
 
1831
12.4.6.3 Additions to Ada
1832
.........................
1833
 
1834
As it does for other languages, GDB makes certain generic extensions to
1835
Ada (*note Expressions::):
1836
 
1837
   * If the expression E is a variable residing in memory (typically a
1838
     local variable or array element) and N is a positive integer, then
1839
     `E@N' displays the values of E and the N-1 adjacent variables
1840
     following it in memory as an array.  In Ada, this operator is
1841
     generally not necessary, since its prime use is in displaying
1842
     parts of an array, and slicing will usually do this in Ada.
1843
     However, there are occasional uses when debugging programs in
1844
     which certain debugging information has been optimized away.
1845
 
1846
   * `B::VAR' means "the variable named VAR that appears in function or
1847
     file B."  When B is a file name, you must typically surround it in
1848
     single quotes.
1849
 
1850
   * The expression `{TYPE} ADDR' means "the variable of type TYPE that
1851
     appears at address ADDR."
1852
 
1853
   * A name starting with `$' is a convenience variable (*note
1854
     Convenience Vars::) or a machine register (*note Registers::).
1855
 
1856
   In addition, GDB provides a few other shortcuts and outright
1857
additions specific to Ada:
1858
 
1859
   * The assignment statement is allowed as an expression, returning
1860
     its right-hand operand as its value.  Thus, you may enter
1861
 
1862
          set x := y + 3
1863
          print A(tmp := y + 1)
1864
 
1865
   * The semicolon is allowed as an "operator,"  returning as its value
1866
     the value of its right-hand operand.  This allows, for example,
1867
     complex conditional breaks:
1868
 
1869
          break f
1870
          condition 1 (report(i); k += 1; A(k) > 100)
1871
 
1872
   * Rather than use catenation and symbolic character names to
1873
     introduce special characters into strings, one may instead use a
1874
     special bracket notation, which is also used to print strings.  A
1875
     sequence of characters of the form `["XX"]' within a string or
1876
     character literal denotes the (single) character whose numeric
1877
     encoding is XX in hexadecimal.  The sequence of characters `["""]'
1878
     also denotes a single quotation mark in strings.   For example,
1879
             "One line.["0a"]Next line.["0a"]"
1880
     contains an ASCII newline character (`Ada.Characters.Latin_1.LF')
1881
     after each period.
1882
 
1883
   * The subtype used as a prefix for the attributes 'Pos, 'Min, and
1884
     'Max is optional (and is ignored in any case).  For example, it is
1885
     valid to write
1886
 
1887
          print 'max(x, y)
1888
 
1889
   * When printing arrays, GDB uses positional notation when the array
1890
     has a lower bound of 1, and uses a modified named notation
1891
     otherwise.  For example, a one-dimensional array of three integers
1892
     with a lower bound of 3 might print as
1893
 
1894
          (3 => 10, 17, 1)
1895
 
1896
     That is, in contrast to valid Ada, only the first component has a
1897
     `=>' clause.
1898
 
1899
   * You may abbreviate attributes in expressions with any unique,
1900
     multi-character subsequence of their names (an exact match gets
1901
     preference).  For example, you may use a'len, a'gth, or a'lh in
1902
     place of  a'length.
1903
 
1904
   * Since Ada is case-insensitive, the debugger normally maps
1905
     identifiers you type to lower case.  The GNAT compiler uses
1906
     upper-case characters for some of its internal identifiers, which
1907
     are normally of no interest to users.  For the rare occasions when
1908
     you actually have to look at them, enclose them in angle brackets
1909
     to avoid the lower-case mapping.  For example,
1910
          gdb print [0]
1911
 
1912
   * Printing an object of class-wide type or dereferencing an
1913
     access-to-class-wide value will display all the components of the
1914
     object's specific type (as indicated by its run-time tag).
1915
     Likewise, component selection on such a value will operate on the
1916
     specific type of the object.
1917
 
1918
 
1919

1920
File: gdb.info,  Node: Stopping Before Main Program,  Next: Ada Glitches,  Prev: Additions to Ada,  Up: Ada
1921
 
1922
12.4.6.4 Stopping at the Very Beginning
1923
.......................................
1924
 
1925
It is sometimes necessary to debug the program during elaboration, and
1926
before reaching the main procedure.  As defined in the Ada Reference
1927
Manual, the elaboration code is invoked from a procedure called
1928
`adainit'.  To run your program up to the beginning of elaboration,
1929
simply use the following two commands: `tbreak adainit' and `run'.
1930
 
1931

1932
File: gdb.info,  Node: Ada Glitches,  Prev: Stopping Before Main Program,  Up: Ada
1933
 
1934
12.4.6.5 Known Peculiarities of Ada Mode
1935
........................................
1936
 
1937
Besides the omissions listed previously (*note Omissions from Ada::),
1938
we know of several problems with and limitations of Ada mode in GDB,
1939
some of which will be fixed with planned future releases of the debugger
1940
and the GNU Ada compiler.
1941
 
1942
   * Currently, the debugger has insufficient information to determine
1943
     whether certain pointers represent pointers to objects or the
1944
     objects themselves.  Thus, the user may have to tack an extra
1945
     `.all' after an expression to get it printed properly.
1946
 
1947
   * Static constants that the compiler chooses not to materialize as
1948
     objects in storage are invisible to the debugger.
1949
 
1950
   * Named parameter associations in function argument lists are
1951
     ignored (the argument lists are treated as positional).
1952
 
1953
   * Many useful library packages are currently invisible to the
1954
     debugger.
1955
 
1956
   * Fixed-point arithmetic, conversions, input, and output is carried
1957
     out using floating-point arithmetic, and may give results that
1958
     only approximate those on the host machine.
1959
 
1960
   * The type of the 'Address attribute may not be `System.Address'.
1961
 
1962
   * The GNAT compiler never generates the prefix `Standard' for any of
1963
     the standard symbols defined by the Ada language.  GDB knows about
1964
     this: it will strip the prefix from names when you use it, and
1965
     will never look for a name you have so qualified among local
1966
     symbols, nor match against symbols in other packages or
1967
     subprograms.  If you have defined entities anywhere in your
1968
     program other than parameters and local variables whose simple
1969
     names match names in `Standard', GNAT's lack of qualification here
1970
     can cause confusion.  When this happens, you can usually resolve
1971
     the confusion by qualifying the problematic names with package
1972
     `Standard' explicitly.
1973
 
1974

1975
File: gdb.info,  Node: Unsupported Languages,  Prev: Supported Languages,  Up: Languages
1976
 
1977
12.5 Unsupported Languages
1978
==========================
1979
 
1980
In addition to the other fully-supported programming languages, GDB
1981
also provides a pseudo-language, called `minimal'.  It does not
1982
represent a real programming language, but provides a set of
1983
capabilities close to what the C or assembly languages provide.  This
1984
should allow most simple operations to be performed while debugging an
1985
application that uses a language currently not supported by GDB.
1986
 
1987
   If the language is set to `auto', GDB will automatically select this
1988
language if the current frame corresponds to an unsupported language.
1989
 
1990

1991
File: gdb.info,  Node: Symbols,  Next: Altering,  Prev: Languages,  Up: Top
1992
 
1993
13 Examining the Symbol Table
1994
*****************************
1995
 
1996
The commands described in this chapter allow you to inquire about the
1997
symbols (names of variables, functions and types) defined in your
1998
program.  This information is inherent in the text of your program and
1999
does not change as your program executes.  GDB finds it in your
2000
program's symbol table, in the file indicated when you started GDB
2001
(*note Choosing Files: File Options.), or by one of the file-management
2002
commands (*note Commands to Specify Files: Files.).
2003
 
2004
   Occasionally, you may need to refer to symbols that contain unusual
2005
characters, which GDB ordinarily treats as word delimiters.  The most
2006
frequent case is in referring to static variables in other source files
2007
(*note Program Variables: Variables.).  File names are recorded in
2008
object files as debugging symbols, but GDB would ordinarily parse a
2009
typical file name, like `foo.c', as the three words `foo' `.' `c'.  To
2010
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
2011
quotes; for example,
2012
 
2013
     p 'foo.c'::x
2014
 
2015
looks up the value of `x' in the scope of the file `foo.c'.
2016
 
2017
`set case-sensitive on'
2018
`set case-sensitive off'
2019
`set case-sensitive auto'
2020
     Normally, when GDB looks up symbols, it matches their names with
2021
     case sensitivity determined by the current source language.
2022
     Occasionally, you may wish to control that.  The command `set
2023
     case-sensitive' lets you do that by specifying `on' for
2024
     case-sensitive matches or `off' for case-insensitive ones.  If you
2025
     specify `auto', case sensitivity is reset to the default suitable
2026
     for the source language.  The default is case-sensitive matches
2027
     for all languages except for Fortran, for which the default is
2028
     case-insensitive matches.
2029
 
2030
`show case-sensitive'
2031
     This command shows the current setting of case sensitivity for
2032
     symbols lookups.
2033
 
2034
`info address SYMBOL'
2035
     Describe where the data for SYMBOL is stored.  For a register
2036
     variable, this says which register it is kept in.  For a
2037
     non-register local variable, this prints the stack-frame offset at
2038
     which the variable is always stored.
2039
 
2040
     Note the contrast with `print &SYMBOL', which does not work at all
2041
     for a register variable, and for a stack local variable prints the
2042
     exact address of the current instantiation of the variable.
2043
 
2044
`info symbol ADDR'
2045
     Print the name of a symbol which is stored at the address ADDR.
2046
     If no symbol is stored exactly at ADDR, GDB prints the nearest
2047
     symbol and an offset from it:
2048
 
2049
          (gdb) info symbol 0x54320
2050
          _initialize_vx + 396 in section .text
2051
 
2052
     This is the opposite of the `info address' command.  You can use
2053
     it to find out the name of a variable or a function given its
2054
     address.
2055
 
2056
`whatis [ARG]'
2057
     Print the data type of ARG, which can be either an expression or a
2058
     data type.  With no argument, print the data type of `$', the last
2059
     value in the value history.  If ARG is an expression, it is not
2060
     actually evaluated, and any side-effecting operations (such as
2061
     assignments or function calls) inside it do not take place.  If
2062
     ARG is a type name, it may be the name of a type or typedef, or
2063
     for C code it may have the form `class CLASS-NAME', `struct
2064
     STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'.  *Note
2065
     Expressions: Expressions.
2066
 
2067
`ptype [ARG]'
2068
     `ptype' accepts the same arguments as `whatis', but prints a
2069
     detailed description of the type, instead of just the name of the
2070
     type.  *Note Expressions: Expressions.
2071
 
2072
     For example, for this variable declaration:
2073
 
2074
          struct complex {double real; double imag;} v;
2075
 
2076
     the two commands give this output:
2077
 
2078
          (gdb) whatis v
2079
          type = struct complex
2080
          (gdb) ptype v
2081
          type = struct complex {
2082
              double real;
2083
              double imag;
2084
          }
2085
 
2086
     As with `whatis', using `ptype' without an argument refers to the
2087
     type of `$', the last value in the value history.
2088
 
2089
     Sometimes, programs use opaque data types or incomplete
2090
     specifications of complex data structure.  If the debug
2091
     information included in the program does not allow GDB to display
2092
     a full declaration of the data type, it will say `
2093
     type>'.  For example, given these declarations:
2094
 
2095
              struct foo;
2096
              struct foo *fooptr;
2097
 
2098
     but no definition for `struct foo' itself, GDB will say:
2099
 
2100
            (gdb) ptype foo
2101
            $1 = 
2102
 
2103
     "Incomplete type" is C terminology for data types that are not
2104
     completely specified.
2105
 
2106
`info types REGEXP'
2107
`info types'
2108
     Print a brief description of all types whose names match the
2109
     regular expression REGEXP (or all types in your program, if you
2110
     supply no argument).  Each complete typename is matched as though
2111
     it were a complete line; thus, `i type value' gives information on
2112
     all types in your program whose names include the string `value',
2113
     but `i type ^value$' gives information only on types whose complete
2114
     name is `value'.
2115
 
2116
     This command differs from `ptype' in two ways: first, like
2117
     `whatis', it does not print a detailed description; second, it
2118
     lists all source files where a type is defined.
2119
 
2120
`info scope LOCATION'
2121
     List all the variables local to a particular scope.  This command
2122
     accepts a LOCATION argument--a function name, a source line, or an
2123
     address preceded by a `*', and prints all the variables local to
2124
     the scope defined by that location.  (*Note Specify Location::, for
2125
     details about supported forms of LOCATION.)  For example:
2126
 
2127
          (gdb) info scope command_line_handler
2128
          Scope for command_line_handler:
2129
          Symbol rl is an argument at stack/frame offset 8, length 4.
2130
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
2131
          Symbol linelength is in static storage at address 0x150a1c, length 4.
2132
          Symbol p is a local variable in register $esi, length 4.
2133
          Symbol p1 is a local variable in register $ebx, length 4.
2134
          Symbol nline is a local variable in register $edx, length 4.
2135
          Symbol repeat is a local variable at frame offset -8, length 4.
2136
 
2137
     This command is especially useful for determining what data to
2138
     collect during a "trace experiment", see *Note collect: Tracepoint
2139
     Actions.
2140
 
2141
`info source'
2142
     Show information about the current source file--that is, the
2143
     source file for the function containing the current point of
2144
     execution:
2145
        * the name of the source file, and the directory containing it,
2146
 
2147
        * the directory it was compiled in,
2148
 
2149
        * its length, in lines,
2150
 
2151
        * which programming language it is written in,
2152
 
2153
        * whether the executable includes debugging information for
2154
          that file, and if so, what format the information is in
2155
          (e.g., STABS, Dwarf 2, etc.), and
2156
 
2157
        * whether the debugging information includes information about
2158
          preprocessor macros.
2159
 
2160
`info sources'
2161
     Print the names of all source files in your program for which
2162
     there is debugging information, organized into two lists: files
2163
     whose symbols have already been read, and files whose symbols will
2164
     be read when needed.
2165
 
2166
`info functions'
2167
     Print the names and data types of all defined functions.
2168
 
2169
`info functions REGEXP'
2170
     Print the names and data types of all defined functions whose
2171
     names contain a match for regular expression REGEXP.  Thus, `info
2172
     fun step' finds all functions whose names include `step'; `info
2173
     fun ^step' finds those whose names start with `step'.  If a
2174
     function name contains characters that conflict with the regular
2175
     expression language (e.g.  `operator*()'), they may be quoted with
2176
     a backslash.
2177
 
2178
`info variables'
2179
     Print the names and data types of all variables that are declared
2180
     outside of functions (i.e. excluding local variables).
2181
 
2182
`info variables REGEXP'
2183
     Print the names and data types of all variables (except for local
2184
     variables) whose names contain a match for regular expression
2185
     REGEXP.
2186
 
2187
`info classes'
2188
`info classes REGEXP'
2189
     Display all Objective-C classes in your program, or (with the
2190
     REGEXP argument) all those matching a particular regular
2191
     expression.
2192
 
2193
`info selectors'
2194
`info selectors REGEXP'
2195
     Display all Objective-C selectors in your program, or (with the
2196
     REGEXP argument) all those matching a particular regular
2197
     expression.
2198
 
2199
     Some systems allow individual object files that make up your
2200
     program to be replaced without stopping and restarting your
2201
     program.  For example, in VxWorks you can simply recompile a
2202
     defective object file and keep on running.  If you are running on
2203
     one of these systems, you can allow GDB to reload the symbols for
2204
     automatically relinked modules:
2205
 
2206
    `set symbol-reloading on'
2207
          Replace symbol definitions for the corresponding source file
2208
          when an object file with a particular name is seen again.
2209
 
2210
    `set symbol-reloading off'
2211
          Do not replace symbol definitions when encountering object
2212
          files of the same name more than once.  This is the default
2213
          state; if you are not running on a system that permits
2214
          automatic relinking of modules, you should leave
2215
          `symbol-reloading' off, since otherwise GDB may discard
2216
          symbols when linking large programs, that may contain several
2217
          modules (from different directories or libraries) with the
2218
          same name.
2219
 
2220
    `show symbol-reloading'
2221
          Show the current `on' or `off' setting.
2222
 
2223
`set opaque-type-resolution on'
2224
     Tell GDB to resolve opaque types.  An opaque type is a type
2225
     declared as a pointer to a `struct', `class', or `union'--for
2226
     example, `struct MyType *'--that is used in one source file
2227
     although the full declaration of `struct MyType' is in another
2228
     source file.  The default is on.
2229
 
2230
     A change in the setting of this subcommand will not take effect
2231
     until the next time symbols for a file are loaded.
2232
 
2233
`set opaque-type-resolution off'
2234
     Tell GDB not to resolve opaque types.  In this case, the type is
2235
     printed as follows:
2236
          {}
2237
 
2238
`show opaque-type-resolution'
2239
     Show whether opaque types are resolved or not.
2240
 
2241
`maint print symbols FILENAME'
2242
`maint print psymbols FILENAME'
2243
`maint print msymbols FILENAME'
2244
     Write a dump of debugging symbol data into the file FILENAME.
2245
     These commands are used to debug the GDB symbol-reading code.  Only
2246
     symbols with debugging data are included.  If you use `maint print
2247
     symbols', GDB includes all the symbols for which it has already
2248
     collected full details: that is, FILENAME reflects symbols for
2249
     only those files whose symbols GDB has read.  You can use the
2250
     command `info sources' to find out which files these are.  If you
2251
     use `maint print psymbols' instead, the dump shows information
2252
     about symbols that GDB only knows partially--that is, symbols
2253
     defined in files that GDB has skimmed, but not yet read
2254
     completely.  Finally, `maint print msymbols' dumps just the
2255
     minimal symbol information required for each object file from
2256
     which GDB has read some symbols.  *Note Commands to Specify Files:
2257
     Files, for a discussion of how GDB reads symbols (in the
2258
     description of `symbol-file').
2259
 
2260
`maint info symtabs [ REGEXP ]'
2261
`maint info psymtabs [ REGEXP ]'
2262
     List the `struct symtab' or `struct partial_symtab' structures
2263
     whose names match REGEXP.  If REGEXP is not given, list them all.
2264
     The output includes expressions which you can copy into a GDB
2265
     debugging this one to examine a particular structure in more
2266
     detail.  For example:
2267
 
2268
          (gdb) maint info psymtabs dwarf2read
2269
          { objfile /home/gnu/build/gdb/gdb
2270
            ((struct objfile *) 0x82e69d0)
2271
            { psymtab /home/gnu/src/gdb/dwarf2read.c
2272
              ((struct partial_symtab *) 0x8474b10)
2273
              readin no
2274
              fullname (null)
2275
              text addresses 0x814d3c8 -- 0x8158074
2276
              globals (* (struct partial_symbol **) 0x8507a08 @ 9)
2277
              statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
2278
              dependencies (none)
2279
            }
2280
          }
2281
          (gdb) maint info symtabs
2282
          (gdb)
2283
     We see that there is one partial symbol table whose filename
2284
     contains the string `dwarf2read', belonging to the `gdb'
2285
     executable; and we see that GDB has not read in any symtabs yet at
2286
     all.  If we set a breakpoint on a function, that will cause GDB to
2287
     read the symtab for the compilation unit containing that function:
2288
 
2289
          (gdb) break dwarf2_psymtab_to_symtab
2290
          Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
2291
          line 1574.
2292
          (gdb) maint info symtabs
2293
          { objfile /home/gnu/build/gdb/gdb
2294
            ((struct objfile *) 0x82e69d0)
2295
            { symtab /home/gnu/src/gdb/dwarf2read.c
2296
              ((struct symtab *) 0x86c1f38)
2297
              dirname (null)
2298
              fullname (null)
2299
              blockvector ((struct blockvector *) 0x86c1bd0) (primary)
2300
              linetable ((struct linetable *) 0x8370fa0)
2301
              debugformat DWARF 2
2302
            }
2303
          }
2304
          (gdb)
2305
 
2306

2307
File: gdb.info,  Node: Altering,  Next: GDB Files,  Prev: Symbols,  Up: Top
2308
 
2309
14 Altering Execution
2310
*********************
2311
 
2312
Once you think you have found an error in your program, you might want
2313
to find out for certain whether correcting the apparent error would
2314
lead to correct results in the rest of the run.  You can find the
2315
answer by experiment, using the GDB features for altering execution of
2316
the program.
2317
 
2318
   For example, you can store new values into variables or memory
2319
locations, give your program a signal, restart it at a different
2320
address, or even return prematurely from a function.
2321
 
2322
* Menu:
2323
 
2324
* Assignment::                  Assignment to variables
2325
* Jumping::                     Continuing at a different address
2326
* Signaling::                   Giving your program a signal
2327
* Returning::                   Returning from a function
2328
* Calling::                     Calling your program's functions
2329
* Patching::                    Patching your program
2330
 
2331

2332
File: gdb.info,  Node: Assignment,  Next: Jumping,  Up: Altering
2333
 
2334
14.1 Assignment to Variables
2335
============================
2336
 
2337
To alter the value of a variable, evaluate an assignment expression.
2338
*Note Expressions: Expressions.  For example,
2339
 
2340
     print x=4
2341
 
2342
stores the value 4 into the variable `x', and then prints the value of
2343
the assignment expression (which is 4).  *Note Using GDB with Different
2344
Languages: Languages, for more information on operators in supported
2345
languages.
2346
 
2347
   If you are not interested in seeing the value of the assignment, use
2348
the `set' command instead of the `print' command.  `set' is really the
2349
same as `print' except that the expression's value is not printed and
2350
is not put in the value history (*note Value History: Value History.).
2351
The expression is evaluated only for its effects.
2352
 
2353
   If the beginning of the argument string of the `set' command appears
2354
identical to a `set' subcommand, use the `set variable' command instead
2355
of just `set'.  This command is identical to `set' except for its lack
2356
of subcommands.  For example, if your program has a variable `width',
2357
you get an error if you try to set a new value with just `set
2358
width=13', because GDB has the command `set width':
2359
 
2360
     (gdb) whatis width
2361
     type = double
2362
     (gdb) p width
2363
     $4 = 13
2364
     (gdb) set width=47
2365
     Invalid syntax in expression.
2366
 
2367
The invalid expression, of course, is `=47'.  In order to actually set
2368
the program's variable `width', use
2369
 
2370
     (gdb) set var width=47
2371
 
2372
   Because the `set' command has many subcommands that can conflict
2373
with the names of program variables, it is a good idea to use the `set
2374
variable' command instead of just `set'.  For example, if your program
2375
has a variable `g', you run into problems if you try to set a new value
2376
with just `set g=4', because GDB has the command `set gnutarget',
2377
abbreviated `set g':
2378
 
2379
     (gdb) whatis g
2380
     type = double
2381
     (gdb) p g
2382
     $1 = 1
2383
     (gdb) set g=4
2384
     (gdb) p g
2385
     $2 = 1
2386
     (gdb) r
2387
     The program being debugged has been started already.
2388
     Start it from the beginning? (y or n) y
2389
     Starting program: /home/smith/cc_progs/a.out
2390
     "/home/smith/cc_progs/a.out": can't open to read symbols:
2391
                                      Invalid bfd target.
2392
     (gdb) show g
2393
     The current BFD target is "=4".
2394
 
2395
The program variable `g' did not change, and you silently set the
2396
`gnutarget' to an invalid value.  In order to set the variable `g', use
2397
 
2398
     (gdb) set var g=4
2399
 
2400
   GDB allows more implicit conversions in assignments than C; you can
2401
freely store an integer value into a pointer variable or vice versa,
2402
and you can convert any structure to any other structure that is the
2403
same length or shorter.
2404
 
2405
   To store values into arbitrary places in memory, use the `{...}'
2406
construct to generate a value of specified type at a specified address
2407
(*note Expressions: Expressions.).  For example, `{int}0x83040' refers
2408
to memory location `0x83040' as an integer (which implies a certain size
2409
and representation in memory), and
2410
 
2411
     set {int}0x83040 = 4
2412
 
2413
stores the value 4 into that memory location.
2414
 
2415

2416
File: gdb.info,  Node: Jumping,  Next: Signaling,  Prev: Assignment,  Up: Altering
2417
 
2418
14.2 Continuing at a Different Address
2419
======================================
2420
 
2421
Ordinarily, when you continue your program, you do so at the place where
2422
it stopped, with the `continue' command.  You can instead continue at
2423
an address of your own choosing, with the following commands:
2424
 
2425
`jump LINESPEC'
2426
`jump LOCATION'
2427
     Resume execution at line LINESPEC or at address given by LOCATION.
2428
     Execution stops again immediately if there is a breakpoint there.
2429
     *Note Specify Location::, for a description of the different
2430
     forms of LINESPEC and LOCATION.  It is common practice to use the
2431
     `tbreak' command in conjunction with `jump'.  *Note Setting
2432
     Breakpoints: Set Breaks.
2433
 
2434
     The `jump' command does not change the current stack frame, or the
2435
     stack pointer, or the contents of any memory location or any
2436
     register other than the program counter.  If line LINESPEC is in a
2437
     different function from the one currently executing, the results
2438
     may be bizarre if the two functions expect different patterns of
2439
     arguments or of local variables.  For this reason, the `jump'
2440
     command requests confirmation if the specified line is not in the
2441
     function currently executing.  However, even bizarre results are
2442
     predictable if you are well acquainted with the machine-language
2443
     code of your program.
2444
 
2445
   On many systems, you can get much the same effect as the `jump'
2446
command by storing a new value into the register `$pc'.  The difference
2447
is that this does not start your program running; it only changes the
2448
address of where it _will_ run when you continue.  For example,
2449
 
2450
     set $pc = 0x485
2451
 
2452
makes the next `continue' command or stepping command execute at
2453
address `0x485', rather than at the address where your program stopped.
2454
*Note Continuing and Stepping: Continuing and Stepping.
2455
 
2456
   The most common occasion to use the `jump' command is to back
2457
up--perhaps with more breakpoints set--over a portion of a program that
2458
has already executed, in order to examine its execution in more detail.
2459
 
2460

2461
File: gdb.info,  Node: Signaling,  Next: Returning,  Prev: Jumping,  Up: Altering
2462
 
2463
14.3 Giving your Program a Signal
2464
=================================
2465
 
2466
`signal SIGNAL'
2467
     Resume execution where your program stopped, but immediately give
2468
     it the signal SIGNAL.  SIGNAL can be the name or the number of a
2469
     signal.  For example, on many systems `signal 2' and `signal
2470
     SIGINT' are both ways of sending an interrupt signal.
2471
 
2472
     Alternatively, if SIGNAL is zero, continue execution without
2473
     giving a signal.  This is useful when your program stopped on
2474
     account of a signal and would ordinary see the signal when resumed
2475
     with the `continue' command; `signal 0' causes it to resume
2476
     without a signal.
2477
 
2478
     `signal' does not repeat when you press  a second time after
2479
     executing the command.
2480
 
2481
   Invoking the `signal' command is not the same as invoking the `kill'
2482
utility from the shell.  Sending a signal with `kill' causes GDB to
2483
decide what to do with the signal depending on the signal handling
2484
tables (*note Signals::).  The `signal' command passes the signal
2485
directly to your program.
2486
 
2487

2488
File: gdb.info,  Node: Returning,  Next: Calling,  Prev: Signaling,  Up: Altering
2489
 
2490
14.4 Returning from a Function
2491
==============================
2492
 
2493
`return'
2494
`return EXPRESSION'
2495
     You can cancel execution of a function call with the `return'
2496
     command.  If you give an EXPRESSION argument, its value is used as
2497
     the function's return value.
2498
 
2499
   When you use `return', GDB discards the selected stack frame (and
2500
all frames within it).  You can think of this as making the discarded
2501
frame return prematurely.  If you wish to specify a value to be
2502
returned, give that value as the argument to `return'.
2503
 
2504
   This pops the selected stack frame (*note Selecting a Frame:
2505
Selection.), and any other frames inside of it, leaving its caller as
2506
the innermost remaining frame.  That frame becomes selected.  The
2507
specified value is stored in the registers used for returning values of
2508
functions.
2509
 
2510
   The `return' command does not resume execution; it leaves the
2511
program stopped in the state that would exist if the function had just
2512
returned.  In contrast, the `finish' command (*note Continuing and
2513
Stepping: Continuing and Stepping.) resumes execution until the
2514
selected stack frame returns naturally.
2515
 
2516

2517
File: gdb.info,  Node: Calling,  Next: Patching,  Prev: Returning,  Up: Altering
2518
 
2519
14.5 Calling Program Functions
2520
==============================
2521
 
2522
`print EXPR'
2523
     Evaluate the expression EXPR and display the resulting value.
2524
     EXPR may include calls to functions in the program being debugged.
2525
 
2526
`call EXPR'
2527
     Evaluate the expression EXPR without displaying `void' returned
2528
     values.
2529
 
2530
     You can use this variant of the `print' command if you want to
2531
     execute a function from your program that does not return anything
2532
     (a.k.a. "a void function"), but without cluttering the output with
2533
     `void' returned values that GDB will otherwise print.  If the
2534
     result is not void, it is printed and saved in the value history.
2535
 
2536
   It is possible for the function you call via the `print' or `call'
2537
command to generate a signal (e.g., if there's a bug in the function,
2538
or if you passed it incorrect arguments).  What happens in that case is
2539
controlled by the `set unwindonsignal' command.
2540
 
2541
`set unwindonsignal'
2542
     Set unwinding of the stack if a signal is received while in a
2543
     function that GDB called in the program being debugged.  If set to
2544
     on, GDB unwinds the stack it created for the call and restores the
2545
     context to what it was before the call.  If set to off (the
2546
     default), GDB stops in the frame where the signal was received.
2547
 
2548
`show unwindonsignal'
2549
     Show the current setting of stack unwinding in the functions
2550
     called by GDB.
2551
 
2552
   Sometimes, a function you wish to call is actually a "weak alias"
2553
for another function.  In such case, GDB might not pick up the type
2554
information, including the types of the function arguments, which
2555
causes GDB to call the inferior function incorrectly.  As a result, the
2556
called function will function erroneously and may even crash.  A
2557
solution to that is to use the name of the aliased function instead.
2558
 
2559

2560
File: gdb.info,  Node: Patching,  Prev: Calling,  Up: Altering
2561
 
2562
14.6 Patching Programs
2563
======================
2564
 
2565
By default, GDB opens the file containing your program's executable
2566
code (or the corefile) read-only.  This prevents accidental alterations
2567
to machine code; but it also prevents you from intentionally patching
2568
your program's binary.
2569
 
2570
   If you'd like to be able to patch the binary, you can specify that
2571
explicitly with the `set write' command.  For example, you might want
2572
to turn on internal debugging flags, or even to make emergency repairs.
2573
 
2574
`set write on'
2575
`set write off'
2576
     If you specify `set write on', GDB opens executable and core files
2577
     for both reading and writing; if you specify `set write off' (the
2578
     default), GDB opens them read-only.
2579
 
2580
     If you have already loaded a file, you must load it again (using
2581
     the `exec-file' or `core-file' command) after changing `set
2582
     write', for your new setting to take effect.
2583
 
2584
`show write'
2585
     Display whether executable files and core files are opened for
2586
     writing as well as reading.
2587
 
2588

2589
File: gdb.info,  Node: GDB Files,  Next: Targets,  Prev: Altering,  Up: Top
2590
 
2591
15 GDB Files
2592
************
2593
 
2594
GDB needs to know the file name of the program to be debugged, both in
2595
order to read its symbol table and in order to start your program.  To
2596
debug a core dump of a previous run, you must also tell GDB the name of
2597
the core dump file.
2598
 
2599
* Menu:
2600
 
2601
* Files::                       Commands to specify files
2602
* Separate Debug Files::        Debugging information in separate files
2603
* Symbol Errors::               Errors reading symbol files
2604
 
2605

2606
File: gdb.info,  Node: Files,  Next: Separate Debug Files,  Up: GDB Files
2607
 
2608
15.1 Commands to Specify Files
2609
==============================
2610
 
2611
You may want to specify executable and core dump file names.  The usual
2612
way to do this is at start-up time, using the arguments to GDB's
2613
start-up commands (*note Getting In and Out of GDB: Invocation.).
2614
 
2615
   Occasionally it is necessary to change to a different file during a
2616
GDB session.  Or you may run GDB and forget to specify a file you want
2617
to use.  Or you are debugging a remote target via `gdbserver' (*note
2618
file: Server.).  In these situations the GDB commands to specify new
2619
files are useful.
2620
 
2621
`file FILENAME'
2622
     Use FILENAME as the program to be debugged.  It is read for its
2623
     symbols and for the contents of pure memory.  It is also the
2624
     program executed when you use the `run' command.  If you do not
2625
     specify a directory and the file is not found in the GDB working
2626
     directory, GDB uses the environment variable `PATH' as a list of
2627
     directories to search, just as the shell does when looking for a
2628
     program to run.  You can change the value of this variable, for
2629
     both GDB and your program, using the `path' command.
2630
 
2631
     You can load unlinked object `.o' files into GDB using the `file'
2632
     command.  You will not be able to "run" an object file, but you
2633
     can disassemble functions and inspect variables.  Also, if the
2634
     underlying BFD functionality supports it, you could use `gdb
2635
     -write' to patch object files using this technique.  Note that GDB
2636
     can neither interpret nor modify relocations in this case, so
2637
     branches and some initialized variables will appear to go to the
2638
     wrong place.  But this feature is still handy from time to time.
2639
 
2640
`file'
2641
     `file' with no argument makes GDB discard any information it has
2642
     on both executable file and the symbol table.
2643
 
2644
`exec-file [ FILENAME ]'
2645
     Specify that the program to be run (but not the symbol table) is
2646
     found in FILENAME.  GDB searches the environment variable `PATH'
2647
     if necessary to locate your program.  Omitting FILENAME means to
2648
     discard information on the executable file.
2649
 
2650
`symbol-file [ FILENAME ]'
2651
     Read symbol table information from file FILENAME.  `PATH' is
2652
     searched when necessary.  Use the `file' command to get both symbol
2653
     table and program to run from the same file.
2654
 
2655
     `symbol-file' with no argument clears out GDB information on your
2656
     program's symbol table.
2657
 
2658
     The `symbol-file' command causes GDB to forget the contents of
2659
     some breakpoints and auto-display expressions.  This is because
2660
     they may contain pointers to the internal data recording symbols
2661
     and data types, which are part of the old symbol table data being
2662
     discarded inside GDB.
2663
 
2664
     `symbol-file' does not repeat if you press  again after
2665
     executing it once.
2666
 
2667
     When GDB is configured for a particular environment, it
2668
     understands debugging information in whatever format is the
2669
     standard generated for that environment; you may use either a GNU
2670
     compiler, or other compilers that adhere to the local conventions.
2671
     Best results are usually obtained from GNU compilers; for example,
2672
     using `GCC' you can generate debugging information for optimized
2673
     code.
2674
 
2675
     For most kinds of object files, with the exception of old SVR3
2676
     systems using COFF, the `symbol-file' command does not normally
2677
     read the symbol table in full right away.  Instead, it scans the
2678
     symbol table quickly to find which source files and which symbols
2679
     are present.  The details are read later, one source file at a
2680
     time, as they are needed.
2681
 
2682
     The purpose of this two-stage reading strategy is to make GDB
2683
     start up faster.  For the most part, it is invisible except for
2684
     occasional pauses while the symbol table details for a particular
2685
     source file are being read.  (The `set verbose' command can turn
2686
     these pauses into messages if desired.  *Note Optional Warnings
2687
     and Messages: Messages/Warnings.)
2688
 
2689
     We have not implemented the two-stage strategy for COFF yet.  When
2690
     the symbol table is stored in COFF format, `symbol-file' reads the
2691
     symbol table data in full right away.  Note that "stabs-in-COFF"
2692
     still does the two-stage strategy, since the debug info is actually
2693
     in stabs format.
2694
 
2695
`symbol-file FILENAME [ -readnow ]'
2696
`file FILENAME [ -readnow ]'
2697
     You can override the GDB two-stage strategy for reading symbol
2698
     tables by using the `-readnow' option with any of the commands that
2699
     load symbol table information, if you want to be sure GDB has the
2700
     entire symbol table available.
2701
 
2702
`core-file [FILENAME]'
2703
`core'
2704
     Specify the whereabouts of a core dump file to be used as the
2705
     "contents of memory".  Traditionally, core files contain only some
2706
     parts of the address space of the process that generated them; GDB
2707
     can access the executable file itself for other parts.
2708
 
2709
     `core-file' with no argument specifies that no core file is to be
2710
     used.
2711
 
2712
     Note that the core file is ignored when your program is actually
2713
     running under GDB.  So, if you have been running your program and
2714
     you wish to debug a core file instead, you must kill the
2715
     subprocess in which the program is running.  To do this, use the
2716
     `kill' command (*note Killing the Child Process: Kill Process.).
2717
 
2718
`add-symbol-file FILENAME ADDRESS'
2719
`add-symbol-file FILENAME ADDRESS [ -readnow ]'
2720
`add-symbol-file FILENAME -sSECTION ADDRESS ...'
2721
     The `add-symbol-file' command reads additional symbol table
2722
     information from the file FILENAME.  You would use this command
2723
     when FILENAME has been dynamically loaded (by some other means)
2724
     into the program that is running.  ADDRESS should be the memory
2725
     address at which the file has been loaded; GDB cannot figure this
2726
     out for itself.  You can additionally specify an arbitrary number
2727
     of `-sSECTION ADDRESS' pairs, to give an explicit section name and
2728
     base address for that section.  You can specify any ADDRESS as an
2729
     expression.
2730
 
2731
     The symbol table of the file FILENAME is added to the symbol table
2732
     originally read with the `symbol-file' command.  You can use the
2733
     `add-symbol-file' command any number of times; the new symbol data
2734
     thus read keeps adding to the old.  To discard all old symbol data
2735
     instead, use the `symbol-file' command without any arguments.
2736
 
2737
     Although FILENAME is typically a shared library file, an
2738
     executable file, or some other object file which has been fully
2739
     relocated for loading into a process, you can also load symbolic
2740
     information from relocatable `.o' files, as long as:
2741
 
2742
        * the file's symbolic information refers only to linker symbols
2743
          defined in that file, not to symbols defined by other object
2744
          files,
2745
 
2746
        * every section the file's symbolic information refers to has
2747
          actually been loaded into the inferior, as it appears in the
2748
          file, and
2749
 
2750
        * you can determine the address at which every section was
2751
          loaded, and provide these to the `add-symbol-file' command.
2752
 
2753
     Some embedded operating systems, like Sun Chorus and VxWorks, can
2754
     load relocatable files into an already running program; such
2755
     systems typically make the requirements above easy to meet.
2756
     However, it's important to recognize that many native systems use
2757
     complex link procedures (`.linkonce' section factoring and C++
2758
     constructor table assembly, for example) that make the
2759
     requirements difficult to meet.  In general, one cannot assume
2760
     that using `add-symbol-file' to read a relocatable object file's
2761
     symbolic information will have the same effect as linking the
2762
     relocatable object file into the program in the normal way.
2763
 
2764
     `add-symbol-file' does not repeat if you press  after using
2765
     it.
2766
 
2767
`add-symbol-file-from-memory ADDRESS'
2768
     Load symbols from the given ADDRESS in a dynamically loaded object
2769
     file whose image is mapped directly into the inferior's memory.
2770
     For example, the Linux kernel maps a `syscall DSO' into each
2771
     process's address space; this DSO provides kernel-specific code for
2772
     some system calls.  The argument can be any expression whose
2773
     evaluation yields the address of the file's shared object file
2774
     header.  For this command to work, you must have used
2775
     `symbol-file' or `exec-file' commands in advance.
2776
 
2777
`add-shared-symbol-files LIBRARY-FILE'
2778
`assf LIBRARY-FILE'
2779
     The `add-shared-symbol-files' command can currently be used only
2780
     in the Cygwin build of GDB on MS-Windows OS, where it is an alias
2781
     for the `dll-symbols' command (*note Cygwin Native::).  GDB
2782
     automatically looks for shared libraries, however if GDB does not
2783
     find yours, you can invoke `add-shared-symbol-files'.  It takes
2784
     one argument: the shared library's file name.  `assf' is a
2785
     shorthand alias for `add-shared-symbol-files'.
2786
 
2787
`section SECTION ADDR'
2788
     The `section' command changes the base address of the named
2789
     SECTION of the exec file to ADDR.  This can be used if the exec
2790
     file does not contain section addresses, (such as in the `a.out'
2791
     format), or when the addresses specified in the file itself are
2792
     wrong.  Each section must be changed separately.  The `info files'
2793
     command, described below, lists all the sections and their
2794
     addresses.
2795
 
2796
`info files'
2797
`info target'
2798
     `info files' and `info target' are synonymous; both print the
2799
     current target (*note Specifying a Debugging Target: Targets.),
2800
     including the names of the executable and core dump files
2801
     currently in use by GDB, and the files from which symbols were
2802
     loaded.  The command `help target' lists all possible targets
2803
     rather than current ones.
2804
 
2805
`maint info sections'
2806
     Another command that can give you extra information about program
2807
     sections is `maint info sections'.  In addition to the section
2808
     information displayed by `info files', this command displays the
2809
     flags and file offset of each section in the executable and core
2810
     dump files.  In addition, `maint info sections' provides the
2811
     following command options (which may be arbitrarily combined):
2812
 
2813
    `ALLOBJ'
2814
          Display sections for all loaded object files, including
2815
          shared libraries.
2816
 
2817
    `SECTIONS'
2818
          Display info only for named SECTIONS.
2819
 
2820
    `SECTION-FLAGS'
2821
          Display info only for sections for which SECTION-FLAGS are
2822
          true.  The section flags that GDB currently knows about are:
2823
         `ALLOC'
2824
               Section will have space allocated in the process when
2825
               loaded.  Set for all sections except those containing
2826
               debug information.
2827
 
2828
         `LOAD'
2829
               Section will be loaded from the file into the child
2830
               process memory.  Set for pre-initialized code and data,
2831
               clear for `.bss' sections.
2832
 
2833
         `RELOC'
2834
               Section needs to be relocated before loading.
2835
 
2836
         `READONLY'
2837
               Section cannot be modified by the child process.
2838
 
2839
         `CODE'
2840
               Section contains executable code only.
2841
 
2842
         `DATA'
2843
               Section contains data only (no executable code).
2844
 
2845
         `ROM'
2846
               Section will reside in ROM.
2847
 
2848
         `CONSTRUCTOR'
2849
               Section contains data for constructor/destructor lists.
2850
 
2851
         `HAS_CONTENTS'
2852
               Section is not empty.
2853
 
2854
         `NEVER_LOAD'
2855
               An instruction to the linker to not output the section.
2856
 
2857
         `COFF_SHARED_LIBRARY'
2858
               A notification to the linker that the section contains
2859
               COFF shared library information.
2860
 
2861
         `IS_COMMON'
2862
               Section contains common symbols.
2863
 
2864
`set trust-readonly-sections on'
2865
     Tell GDB that readonly sections in your object file really are
2866
     read-only (i.e. that their contents will not change).  In that
2867
     case, GDB can fetch values from these sections out of the object
2868
     file, rather than from the target program.  For some targets
2869
     (notably embedded ones), this can be a significant enhancement to
2870
     debugging performance.
2871
 
2872
     The default is off.
2873
 
2874
`set trust-readonly-sections off'
2875
     Tell GDB not to trust readonly sections.  This means that the
2876
     contents of the section might change while the program is running,
2877
     and must therefore be fetched from the target when needed.
2878
 
2879
`show trust-readonly-sections'
2880
     Show the current setting of trusting readonly sections.
2881
 
2882
   All file-specifying commands allow both absolute and relative file
2883
names as arguments.  GDB always converts the file name to an absolute
2884
file name and remembers it that way.
2885
 
2886
   GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and
2887
IBM RS/6000 AIX shared libraries.
2888
 
2889
   On MS-Windows GDB must be linked with the Expat library to support
2890
shared libraries.  *Note Expat::.
2891
 
2892
   GDB automatically loads symbol definitions from shared libraries
2893
when you use the `run' command, or when you examine a core file.
2894
(Before you issue the `run' command, GDB does not understand references
2895
to a function in a shared library, however--unless you are debugging a
2896
core file).
2897
 
2898
   On HP-UX, if the program loads a library explicitly, GDB
2899
automatically loads the symbols at the time of the `shl_load' call.
2900
 
2901
   There are times, however, when you may wish to not automatically load
2902
symbol definitions from shared libraries, such as when they are
2903
particularly large or there are many of them.
2904
 
2905
   To control the automatic loading of shared library symbols, use the
2906
commands:
2907
 
2908
`set auto-solib-add MODE'
2909
     If MODE is `on', symbols from all shared object libraries will be
2910
     loaded automatically when the inferior begins execution, you
2911
     attach to an independently started inferior, or when the dynamic
2912
     linker informs GDB that a new library has been loaded.  If MODE is
2913
     `off', symbols must be loaded manually, using the `sharedlibrary'
2914
     command.  The default value is `on'.
2915
 
2916
     If your program uses lots of shared libraries with debug info that
2917
     takes large amounts of memory, you can decrease the GDB memory
2918
     footprint by preventing it from automatically loading the symbols
2919
     from shared libraries.  To that end, type `set auto-solib-add off'
2920
     before running the inferior, then load each library whose debug
2921
     symbols you do need with `sharedlibrary REGEXP', where REGEXP is a
2922
     regular expression that matches the libraries whose symbols you
2923
     want to be loaded.
2924
 
2925
`show auto-solib-add'
2926
     Display the current autoloading mode.
2927
 
2928
   To explicitly load shared library symbols, use the `sharedlibrary'
2929
command:
2930
 
2931
`info share'
2932
`info sharedlibrary'
2933
     Print the names of the shared libraries which are currently loaded.
2934
 
2935
`sharedlibrary REGEX'
2936
`share REGEX'
2937
     Load shared object library symbols for files matching a Unix
2938
     regular expression.  As with files loaded automatically, it only
2939
     loads shared libraries required by your program for a core file or
2940
     after typing `run'.  If REGEX is omitted all shared libraries
2941
     required by your program are loaded.
2942
 
2943
`nosharedlibrary'
2944
     Unload all shared object library symbols.  This discards all
2945
     symbols that have been loaded from all shared libraries.  Symbols
2946
     from shared libraries that were loaded by explicit user requests
2947
     are not discarded.
2948
 
2949
   Sometimes you may wish that GDB stops and gives you control when any
2950
of shared library events happen.  Use the `set stop-on-solib-events'
2951
command for this:
2952
 
2953
`set stop-on-solib-events'
2954
     This command controls whether GDB should give you control when the
2955
     dynamic linker notifies it about some shared library event.  The
2956
     most common event of interest is loading or unloading of a new
2957
     shared library.
2958
 
2959
`show stop-on-solib-events'
2960
     Show whether GDB stops and gives you control when shared library
2961
     events happen.
2962
 
2963
   Shared libraries are also supported in many cross or remote debugging
2964
configurations.  A copy of the target's libraries need to be present on
2965
the host system; they need to be the same as the target libraries,
2966
although the copies on the target can be stripped as long as the copies
2967
on the host are not.
2968
 
2969
   For remote debugging, you need to tell GDB where the target
2970
libraries are, so that it can load the correct copies--otherwise, it
2971
may try to load the host's libraries.  GDB has two variables to specify
2972
the search directories for target libraries.
2973
 
2974
`set sysroot PATH'
2975
     Use PATH as the system root for the program being debugged.  Any
2976
     absolute shared library paths will be prefixed with PATH; many
2977
     runtime loaders store the absolute paths to the shared library in
2978
     the target program's memory.  If you use `set sysroot' to find
2979
     shared libraries, they need to be laid out in the same way that
2980
     they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy
2981
     under PATH.
2982
 
2983
     The `set solib-absolute-prefix' command is an alias for `set
2984
     sysroot'.
2985
 
2986
     You can set the default system root by using the configure-time
2987
     `--with-sysroot' option.  If the system root is inside GDB's
2988
     configured binary prefix (set with `--prefix' or `--exec-prefix'),
2989
     then the default system root will be updated automatically if the
2990
     installed GDB is moved to a new location.
2991
 
2992
`show sysroot'
2993
     Display the current shared library prefix.
2994
 
2995
`set solib-search-path PATH'
2996
     If this variable is set, PATH is a colon-separated list of
2997
     directories to search for shared libraries.  `solib-search-path'
2998
     is used after `sysroot' fails to locate the library, or if the
2999
     path to the library is relative instead of absolute.  If you want
3000
     to use `solib-search-path' instead of `sysroot', be sure to set
3001
     `sysroot' to a nonexistent directory to prevent GDB from finding
3002
     your host's libraries.  `sysroot' is preferred; setting it to a
3003
     nonexistent directory may interfere with automatic loading of
3004
     shared library symbols.
3005
 
3006
`show solib-search-path'
3007
     Display the current shared library search path.
3008
 
3009

3010
File: gdb.info,  Node: Separate Debug Files,  Next: Symbol Errors,  Prev: Files,  Up: GDB Files
3011
 
3012
15.2 Debugging Information in Separate Files
3013
============================================
3014
 
3015
GDB allows you to put a program's debugging information in a file
3016
separate from the executable itself, in a way that allows GDB to find
3017
and load the debugging information automatically.  Since debugging
3018
information can be very large--sometimes larger than the executable
3019
code itself--some systems distribute debugging information for their
3020
executables in separate files, which users can install only when they
3021
need to debug a problem.
3022
 
3023
   GDB supports two ways of specifying the separate debug info file:
3024
 
3025
   * The executable contains a "debug link" that specifies the name of
3026
     the separate debug info file.  The separate debug file's name is
3027
     usually `EXECUTABLE.debug', where EXECUTABLE is the name of the
3028
     corresponding executable file without leading directories (e.g.,
3029
     `ls.debug' for `/usr/bin/ls').  In addition, the debug link
3030
     specifies a CRC32 checksum for the debug file, which GDB uses to
3031
     validate that the executable and the debug file came from the same
3032
     build.
3033
 
3034
   * The executable contains a "build ID", a unique bit string that is
3035
     also present in the corresponding debug info file.  (This is
3036
     supported only on some operating systems, notably those which use
3037
     the ELF format for binary files and the GNU Binutils.)  For more
3038
     details about this feature, see the description of the `--build-id'
3039
     command-line option in *Note Command Line Options:
3040
     (ld.info)Options.  The debug info file's name is not specified
3041
     explicitly by the build ID, but can be computed from the build ID,
3042
     see below.
3043
 
3044
   Depending on the way the debug info file is specified, GDB uses two
3045
different methods of looking for the debug file:
3046
 
3047
   * For the "debug link" method, GDB looks up the named file in the
3048
     directory of the executable file, then in a subdirectory of that
3049
     directory named `.debug', and finally under the global debug
3050
     directory, in a subdirectory whose name is identical to the leading
3051
     directories of the executable's absolute file name.
3052
 
3053
   * For the "build ID" method, GDB looks in the `.build-id'
3054
     subdirectory of the global debug directory for a file named
3055
     `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of
3056
     the build ID bit string, and NNNNNNNN are the rest of the bit
3057
     string.  (Real build ID strings are 32 or more hex characters, not
3058
     10.)
3059
 
3060
   So, for example, suppose you ask GDB to debug `/usr/bin/ls', which
3061
has a debug link that specifies the file `ls.debug', and a build ID
3062
whose value in hex is `abcdef1234'.  If the global debug directory is
3063
`/usr/lib/debug', then GDB will look for the following debug
3064
information files, in the indicated order:
3065
 
3066
   - `/usr/lib/debug/.build-id/ab/cdef1234.debug'
3067
 
3068
   - `/usr/bin/ls.debug'
3069
 
3070
   - `/usr/bin/.debug/ls.debug'
3071
 
3072
   - `/usr/lib/debug/usr/bin/ls.debug'.
3073
 
3074
   You can set the global debugging info directory's name, and view the
3075
name GDB is currently using.
3076
 
3077
`set debug-file-directory DIRECTORY'
3078
     Set the directory which GDB searches for separate debugging
3079
     information files to DIRECTORY.
3080
 
3081
`show debug-file-directory'
3082
     Show the directory GDB searches for separate debugging information
3083
     files.
3084
 
3085
 
3086
   A debug link is a special section of the executable file named
3087
`.gnu_debuglink'.  The section must contain:
3088
 
3089
   * A filename, with any leading directory components removed,
3090
     followed by a zero byte,
3091
 
3092
   * zero to three bytes of padding, as needed to reach the next
3093
     four-byte boundary within the section, and
3094
 
3095
   * a four-byte CRC checksum, stored in the same endianness used for
3096
     the executable file itself.  The checksum is computed on the
3097
     debugging information file's full contents by the function given
3098
     below, passing zero as the CRC argument.
3099
 
3100
   Any executable file format can carry a debug link, as long as it can
3101
contain a section named `.gnu_debuglink' with the contents described
3102
above.
3103
 
3104
   The build ID is a special section in the executable file (and in
3105
other ELF binary files that GDB may consider).  This section is often
3106
named `.note.gnu.build-id', but that name is not mandatory.  It
3107
contains unique identification for the built files--the ID remains the
3108
same across multiple builds of the same build tree.  The default
3109
algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the
3110
content for the build ID string.  The same section with an identical
3111
value is present in the original built binary with symbols, in its
3112
stripped variant, and in the separate debugging information file.
3113
 
3114
   The debugging information file itself should be an ordinary
3115
executable, containing a full set of linker symbols, sections, and
3116
debugging information.  The sections of the debugging information file
3117
should have the same names, addresses, and sizes as the original file,
3118
but they need not contain any data--much like a `.bss' section in an
3119
ordinary executable.
3120
 
3121
   The GNU binary utilities (Binutils) package includes the `objcopy'
3122
utility that can produce the separated executable / debugging
3123
information file pairs using the following commands:
3124
 
3125
     objcopy --only-keep-debug foo foo.debug
3126
     strip -g foo
3127
 
3128
These commands remove the debugging information from the executable
3129
file `foo' and place it in the file `foo.debug'.  You can use the
3130
first, second or both methods to link the two files:
3131
 
3132
   * The debug link method needs the following additional command to
3133
     also leave behind a debug link in `foo':
3134
 
3135
          objcopy --add-gnu-debuglink=foo.debug foo
3136
 
3137
     Ulrich Drepper's `elfutils' package, starting with version 0.53,
3138
     contains a version of the `strip' command such that the command
3139
     `strip foo -f foo.debug' has the same functionality as the two
3140
     `objcopy' commands and the `ln -s' command above, together.
3141
 
3142
   * Build ID gets embedded into the main executable using `ld
3143
     --build-id' or the GCC counterpart `gcc -Wl,--build-id'.  Build ID
3144
     support plus compatibility fixes for debug files separation are
3145
     present in GNU binary utilities (Binutils) package since version
3146
     2.18.
3147
 
3148
Since there are many different ways to compute CRC's for the debug link
3149
(different polynomials, reversals, byte ordering, etc.), the simplest
3150
way to describe the CRC used in `.gnu_debuglink' sections is to give
3151
the complete code for a function that computes it:
3152
 
3153
     unsigned long
3154
     gnu_debuglink_crc32 (unsigned long crc,
3155
                          unsigned char *buf, size_t len)
3156
     {
3157
       static const unsigned long crc32_table[256] =
3158
         {
3159
           0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
3160
           0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
3161
           0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
3162
           0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
3163
           0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
3164
           0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
3165
           0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
3166
           0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
3167
           0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
3168
           0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
3169
           0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
3170
           0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
3171
           0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
3172
           0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
3173
           0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
3174
           0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
3175
           0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
3176
           0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
3177
           0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
3178
           0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
3179
           0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
3180
           0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
3181
           0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
3182
           0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
3183
           0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
3184
           0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
3185
           0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
3186
           0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
3187
           0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
3188
           0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
3189
           0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
3190
           0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
3191
           0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
3192
           0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
3193
           0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
3194
           0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
3195
           0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
3196
           0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
3197
           0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
3198
           0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
3199
           0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
3200
           0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
3201
           0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
3202
           0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
3203
           0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
3204
           0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
3205
           0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
3206
           0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
3207
           0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
3208
           0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
3209
           0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
3210
           0x2d02ef8d
3211
         };
3212
       unsigned char *end;
3213
 
3214
       crc = ~crc & 0xffffffff;
3215
       for (end = buf + len; buf < end; ++buf)
3216
         crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
3217
       return ~crc & 0xffffffff;
3218
     }
3219
 
3220
This computation does not apply to the "build ID" method.
3221
 
3222

3223
File: gdb.info,  Node: Symbol Errors,  Prev: Separate Debug Files,  Up: GDB Files
3224
 
3225
15.3 Errors Reading Symbol Files
3226
================================
3227
 
3228
While reading a symbol file, GDB occasionally encounters problems, such
3229
as symbol types it does not recognize, or known bugs in compiler
3230
output.  By default, GDB does not notify you of such problems, since
3231
they are relatively common and primarily of interest to people
3232
debugging compilers.  If you are interested in seeing information about
3233
ill-constructed symbol tables, you can either ask GDB to print only one
3234
message about each such type of problem, no matter how many times the
3235
problem occurs; or you can ask GDB to print more messages, to see how
3236
many times the problems occur, with the `set complaints' command (*note
3237
Optional Warnings and Messages: Messages/Warnings.).
3238
 
3239
   The messages currently printed, and their meanings, include:
3240
 
3241
`inner block not inside outer block in SYMBOL'
3242
     The symbol information shows where symbol scopes begin and end
3243
     (such as at the start of a function or a block of statements).
3244
     This error indicates that an inner scope block is not fully
3245
     contained in its outer scope blocks.
3246
 
3247
     GDB circumvents the problem by treating the inner block as if it
3248
     had the same scope as the outer block.  In the error message,
3249
     SYMBOL may be shown as "`(don't know)'" if the outer block is not a
3250
     function.
3251
 
3252
`block at ADDRESS out of order'
3253
     The symbol information for symbol scope blocks should occur in
3254
     order of increasing addresses.  This error indicates that it does
3255
     not do so.
3256
 
3257
     GDB does not circumvent this problem, and has trouble locating
3258
     symbols in the source file whose symbols it is reading.  (You can
3259
     often determine what source file is affected by specifying `set
3260
     verbose on'.  *Note Optional Warnings and Messages:
3261
     Messages/Warnings.)
3262
 
3263
`bad block start address patched'
3264
     The symbol information for a symbol scope block has a start address
3265
     smaller than the address of the preceding source line.  This is
3266
     known to occur in the SunOS 4.1.1 (and earlier) C compiler.
3267
 
3268
     GDB circumvents the problem by treating the symbol scope block as
3269
     starting on the previous source line.
3270
 
3271
`bad string table offset in symbol N'
3272
     Symbol number N contains a pointer into the string table which is
3273
     larger than the size of the string table.
3274
 
3275
     GDB circumvents the problem by considering the symbol to have the
3276
     name `foo', which may cause other problems if many symbols end up
3277
     with this name.
3278
 
3279
`unknown symbol type `0xNN''
3280
     The symbol information contains new data types that GDB does not
3281
     yet know how to read.  `0xNN' is the symbol type of the
3282
     uncomprehended information, in hexadecimal.
3283
 
3284
     GDB circumvents the error by ignoring this symbol information.
3285
     This usually allows you to debug your program, though certain
3286
     symbols are not accessible.  If you encounter such a problem and
3287
     feel like debugging it, you can debug `gdb' with itself, breakpoint
3288
     on `complain', then go up to the function `read_dbx_symtab' and
3289
     examine `*bufp' to see the symbol.
3290
 
3291
`stub type has NULL name'
3292
     GDB could not find the full definition for a struct or class.
3293
 
3294
`const/volatile indicator missing (ok if using g++ v1.x), got...'
3295
     The symbol information for a C++ member function is missing some
3296
     information that recent versions of the compiler should have
3297
     output for it.
3298
 
3299
`info mismatch between compiler and debugger'
3300
     GDB could not parse a type specification output by the compiler.
3301
 
3302
 
3303

3304
File: gdb.info,  Node: Targets,  Next: Remote Debugging,  Prev: GDB Files,  Up: Top
3305
 
3306
16 Specifying a Debugging Target
3307
********************************
3308
 
3309
A "target" is the execution environment occupied by your program.
3310
 
3311
   Often, GDB runs in the same host environment as your program; in
3312
that case, the debugging target is specified as a side effect when you
3313
use the `file' or `core' commands.  When you need more flexibility--for
3314
example, running GDB on a physically separate host, or controlling a
3315
standalone system over a serial port or a realtime system over a TCP/IP
3316
connection--you can use the `target' command to specify one of the
3317
target types configured for GDB (*note Commands for Managing Targets:
3318
Target Commands.).
3319
 
3320
   It is possible to build GDB for several different "target
3321
architectures".  When GDB is built like that, you can choose one of the
3322
available architectures with the `set architecture' command.
3323
 
3324
`set architecture ARCH'
3325
     This command sets the current target architecture to ARCH.  The
3326
     value of ARCH can be `"auto"', in addition to one of the supported
3327
     architectures.
3328
 
3329
`show architecture'
3330
     Show the current target architecture.
3331
 
3332
`set processor'
3333
`processor'
3334
     These are alias commands for, respectively, `set architecture' and
3335
     `show architecture'.
3336
 
3337
* Menu:
3338
 
3339
* Active Targets::              Active targets
3340
* Target Commands::             Commands for managing targets
3341
* Byte Order::                  Choosing target byte order
3342
 
3343

3344
File: gdb.info,  Node: Active Targets,  Next: Target Commands,  Up: Targets
3345
 
3346
16.1 Active Targets
3347
===================
3348
 
3349
There are three classes of targets: processes, core files, and
3350
executable files.  GDB can work concurrently on up to three active
3351
targets, one in each class.  This allows you to (for example) start a
3352
process and inspect its activity without abandoning your work on a core
3353
file.
3354
 
3355
   For example, if you execute `gdb a.out', then the executable file
3356
`a.out' is the only active target.  If you designate a core file as
3357
well--presumably from a prior run that crashed and coredumped--then GDB
3358
has two active targets and uses them in tandem, looking first in the
3359
corefile target, then in the executable file, to satisfy requests for
3360
memory addresses.  (Typically, these two classes of target are
3361
complementary, since core files contain only a program's read-write
3362
memory--variables and so on--plus machine status, while executable
3363
files contain only the program text and initialized data.)
3364
 
3365
   When you type `run', your executable file becomes an active process
3366
target as well.  When a process target is active, all GDB commands
3367
requesting memory addresses refer to that target; addresses in an
3368
active core file or executable file target are obscured while the
3369
process target is active.
3370
 
3371
   Use the `core-file' and `exec-file' commands to select a new core
3372
file or executable target (*note Commands to Specify Files: Files.).
3373
To specify as a target a process that is already running, use the
3374
`attach' command (*note Debugging an Already-running Process: Attach.).
3375
 
3376

3377
File: gdb.info,  Node: Target Commands,  Next: Byte Order,  Prev: Active Targets,  Up: Targets
3378
 
3379
16.2 Commands for Managing Targets
3380
==================================
3381
 
3382
`target TYPE PARAMETERS'
3383
     Connects the GDB host environment to a target machine or process.
3384
     A target is typically a protocol for talking to debugging
3385
     facilities.  You use the argument TYPE to specify the type or
3386
     protocol of the target machine.
3387
 
3388
     Further PARAMETERS are interpreted by the target protocol, but
3389
     typically include things like device names or host names to connect
3390
     with, process numbers, and baud rates.
3391
 
3392
     The `target' command does not repeat if you press  again
3393
     after executing the command.
3394
 
3395
`help target'
3396
     Displays the names of all targets available.  To display targets
3397
     currently selected, use either `info target' or `info files'
3398
     (*note Commands to Specify Files: Files.).
3399
 
3400
`help target NAME'
3401
     Describe a particular target, including any parameters necessary to
3402
     select it.
3403
 
3404
`set gnutarget ARGS'
3405
     GDB uses its own library BFD to read your files.  GDB knows
3406
     whether it is reading an "executable", a "core", or a ".o" file;
3407
     however, you can specify the file format with the `set gnutarget'
3408
     command.  Unlike most `target' commands, with `gnutarget' the
3409
     `target' refers to a program, not a machine.
3410
 
3411
          _Warning:_ To specify a file format with `set gnutarget', you
3412
          must know the actual BFD name.
3413
 
3414
     *Note Commands to Specify Files: Files.
3415
 
3416
`show gnutarget'
3417
     Use the `show gnutarget' command to display what file format
3418
     `gnutarget' is set to read.  If you have not set `gnutarget', GDB
3419
     will determine the file format for each file automatically, and
3420
     `show gnutarget' displays `The current BDF target is "auto"'.
3421
 
3422
   Here are some common targets (available, or not, depending on the GDB
3423
configuration):
3424
 
3425
`target exec PROGRAM'
3426
     An executable file.  `target exec PROGRAM' is the same as
3427
     `exec-file PROGRAM'.
3428
 
3429
`target core FILENAME'
3430
     A core dump file.  `target core FILENAME' is the same as
3431
     `core-file FILENAME'.
3432
 
3433
`target remote MEDIUM'
3434
     A remote system connected to GDB via a serial line or network
3435
     connection.  This command tells GDB to use its own remote protocol
3436
     over MEDIUM for debugging.  *Note Remote Debugging::.
3437
 
3438
     For example, if you have a board connected to `/dev/ttya' on the
3439
     machine running GDB, you could say:
3440
 
3441
          target remote /dev/ttya
3442
 
3443
     `target remote' supports the `load' command.  This is only useful
3444
     if you have some other way of getting the stub to the target
3445
     system, and you can put it somewhere in memory where it won't get
3446
     clobbered by the download.
3447
 
3448
`target sim'
3449
     Builtin CPU simulator.  GDB includes simulators for most
3450
     architectures.  In general,
3451
                  target sim
3452
                  load
3453
                  run
3454
     works; however, you cannot assume that a specific memory map,
3455
     device drivers, or even basic I/O is available, although some
3456
     simulators do provide these.  For info about any
3457
     processor-specific simulator details, see the appropriate section
3458
     in *Note Embedded Processors: Embedded Processors.
3459
 
3460
 
3461
   Some configurations may include these targets as well:
3462
 
3463
`target nrom DEV'
3464
     NetROM ROM emulator.  This target only supports downloading.
3465
 
3466
 
3467
   Different targets are available on different configurations of GDB;
3468
your configuration may have more or fewer targets.
3469
 
3470
   Many remote targets require you to download the executable's code
3471
once you've successfully established a connection.  You may wish to
3472
control various aspects of this process.
3473
 
3474
`set hash'
3475
     This command controls whether a hash mark `#' is displayed while
3476
     downloading a file to the remote monitor.  If on, a hash mark is
3477
     displayed after each S-record is successfully downloaded to the
3478
     monitor.
3479
 
3480
`show hash'
3481
     Show the current status of displaying the hash mark.
3482
 
3483
`set debug monitor'
3484
     Enable or disable display of communications messages between GDB
3485
     and the remote monitor.
3486
 
3487
`show debug monitor'
3488
     Show the current status of displaying communications between GDB
3489
     and the remote monitor.
3490
 
3491
`load FILENAME'
3492
     Depending on what remote debugging facilities are configured into
3493
     GDB, the `load' command may be available.  Where it exists, it is
3494
     meant to make FILENAME (an executable) available for debugging on
3495
     the remote system--by downloading, or dynamic linking, for example.
3496
     `load' also records the FILENAME symbol table in GDB, like the
3497
     `add-symbol-file' command.
3498
 
3499
     If your GDB does not have a `load' command, attempting to execute
3500
     it gets the error message "`You can't do that when your target is
3501
     ...'"
3502
 
3503
     The file is loaded at whatever address is specified in the
3504
     executable.  For some object file formats, you can specify the
3505
     load address when you link the program; for other formats, like
3506
     a.out, the object file format specifies a fixed address.
3507
 
3508
     Depending on the remote side capabilities, GDB may be able to load
3509
     programs into flash memory.
3510
 
3511
     `load' does not repeat if you press  again after using it.
3512
 
3513

3514
File: gdb.info,  Node: Byte Order,  Prev: Target Commands,  Up: Targets
3515
 
3516
16.3 Choosing Target Byte Order
3517
===============================
3518
 
3519
Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
3520
offer the ability to run either big-endian or little-endian byte
3521
orders.  Usually the executable or symbol will include a bit to
3522
designate the endian-ness, and you will not need to worry about which
3523
to use.  However, you may still find it useful to adjust GDB's idea of
3524
processor endian-ness manually.
3525
 
3526
`set endian big'
3527
     Instruct GDB to assume the target is big-endian.
3528
 
3529
`set endian little'
3530
     Instruct GDB to assume the target is little-endian.
3531
 
3532
`set endian auto'
3533
     Instruct GDB to use the byte order associated with the executable.
3534
 
3535
`show endian'
3536
     Display GDB's current idea of the target byte order.
3537
 
3538
 
3539
   Note that these commands merely adjust interpretation of symbolic
3540
data on the host, and that they have absolutely no effect on the target
3541
system.
3542
 
3543

3544
File: gdb.info,  Node: Remote Debugging,  Next: Configurations,  Prev: Targets,  Up: Top
3545
 
3546
17 Debugging Remote Programs
3547
****************************
3548
 
3549
If you are trying to debug a program running on a machine that cannot
3550
run GDB in the usual way, it is often useful to use remote debugging.
3551
For example, you might use remote debugging on an operating system
3552
kernel, or on a small system which does not have a general purpose
3553
operating system powerful enough to run a full-featured debugger.
3554
 
3555
   Some configurations of GDB have special serial or TCP/IP interfaces
3556
to make this work with particular debugging targets.  In addition, GDB
3557
comes with a generic serial protocol (specific to GDB, but not specific
3558
to any particular target system) which you can use if you write the
3559
remote stubs--the code that runs on the remote system to communicate
3560
with GDB.
3561
 
3562
   Other remote targets may be available in your configuration of GDB;
3563
use `help target' to list them.
3564
 
3565
* Menu:
3566
 
3567
* Connecting::                  Connecting to a remote target
3568
* File Transfer::               Sending files to a remote system
3569
* Server::                      Using the gdbserver program
3570
* Remote Configuration::        Remote configuration
3571
* Remote Stub::                 Implementing a remote stub
3572
 
3573

3574
File: gdb.info,  Node: Connecting,  Next: File Transfer,  Up: Remote Debugging
3575
 
3576
17.1 Connecting to a Remote Target
3577
==================================
3578
 
3579
On the GDB host machine, you will need an unstripped copy of your
3580
program, since GDB needs symbol and debugging information.  Start up
3581
GDB as usual, using the name of the local copy of your program as the
3582
first argument.
3583
 
3584
   GDB can communicate with the target over a serial line, or over an
3585
IP network using TCP or UDP.  In each case, GDB uses the same protocol
3586
for debugging your program; only the medium carrying the debugging
3587
packets varies.  The `target remote' command establishes a connection
3588
to the target.  Its arguments indicate which medium to use:
3589
 
3590
`target remote SERIAL-DEVICE'
3591
     Use SERIAL-DEVICE to communicate with the target.  For example, to
3592
     use a serial line connected to the device named `/dev/ttyb':
3593
 
3594
          target remote /dev/ttyb
3595
 
3596
     If you're using a serial line, you may want to give GDB the
3597
     `--baud' option, or use the `set remotebaud' command (*note set
3598
     remotebaud: Remote Configuration.) before the `target' command.
3599
 
3600
`target remote `HOST:PORT''
3601
`target remote `tcp:HOST:PORT''
3602
     Debug using a TCP connection to PORT on HOST.  The HOST may be
3603
     either a host name or a numeric IP address; PORT must be a decimal
3604
     number.  The HOST could be the target machine itself, if it is
3605
     directly connected to the net, or it might be a terminal server
3606
     which in turn has a serial line to the target.
3607
 
3608
     For example, to connect to port 2828 on a terminal server named
3609
     `manyfarms':
3610
 
3611
          target remote manyfarms:2828
3612
 
3613
     If your remote target is actually running on the same machine as
3614
     your debugger session (e.g. a simulator for your target running on
3615
     the same host), you can omit the hostname.  For example, to
3616
     connect to port 1234 on your local machine:
3617
 
3618
          target remote :1234
3619
     Note that the colon is still required here.
3620
 
3621
`target remote `udp:HOST:PORT''
3622
     Debug using UDP packets to PORT on HOST.  For example, to connect
3623
     to UDP port 2828 on a terminal server named `manyfarms':
3624
 
3625
          target remote udp:manyfarms:2828
3626
 
3627
     When using a UDP connection for remote debugging, you should keep
3628
     in mind that the `U' stands for "Unreliable".  UDP can silently
3629
     drop packets on busy or unreliable networks, which will cause
3630
     havoc with your debugging session.
3631
 
3632
`target remote | COMMAND'
3633
     Run COMMAND in the background and communicate with it using a
3634
     pipe.  The COMMAND is a shell command, to be parsed and expanded
3635
     by the system's command shell, `/bin/sh'; it should expect remote
3636
     protocol packets on its standard input, and send replies on its
3637
     standard output.  You could use this to run a stand-alone simulator
3638
     that speaks the remote debugging protocol, to make net connections
3639
     using programs like `ssh', or for other similar tricks.
3640
 
3641
     If COMMAND closes its standard output (perhaps by exiting), GDB
3642
     will try to send it a `SIGTERM' signal.  (If the program has
3643
     already exited, this will have no effect.)
3644
 
3645
 
3646
   Once the connection has been established, you can use all the usual
3647
commands to examine and change data and to step and continue the remote
3648
program.
3649
 
3650
   Whenever GDB is waiting for the remote program, if you type the
3651
interrupt character (often `Ctrl-c'), GDB attempts to stop the program.
3652
This may or may not succeed, depending in part on the hardware and the
3653
serial drivers the remote system uses.  If you type the interrupt
3654
character once again, GDB displays this prompt:
3655
 
3656
     Interrupted while waiting for the program.
3657
     Give up (and stop debugging it)?  (y or n)
3658
 
3659
   If you type `y', GDB abandons the remote debugging session.  (If you
3660
decide you want to try again later, you can use `target remote' again
3661
to connect once more.)  If you type `n', GDB goes back to waiting.
3662
 
3663
`detach'
3664
     When you have finished debugging the remote program, you can use
3665
     the `detach' command to release it from GDB control.  Detaching
3666
     from the target normally resumes its execution, but the results
3667
     will depend on your particular remote stub.  After the `detach'
3668
     command, GDB is free to connect to another target.
3669
 
3670
`disconnect'
3671
     The `disconnect' command behaves like `detach', except that the
3672
     target is generally not resumed.  It will wait for GDB (this
3673
     instance or another one) to connect and continue debugging.  After
3674
     the `disconnect' command, GDB is again free to connect to another
3675
     target.
3676
 
3677
`monitor CMD'
3678
     This command allows you to send arbitrary commands directly to the
3679
     remote monitor.  Since GDB doesn't care about the commands it
3680
     sends like this, this command is the way to extend GDB--you can
3681
     add new commands that only the external monitor will understand
3682
     and implement.
3683
 
3684

3685
File: gdb.info,  Node: File Transfer,  Next: Server,  Prev: Connecting,  Up: Remote Debugging
3686
 
3687
17.2 Sending files to a remote system
3688
=====================================
3689
 
3690
Some remote targets offer the ability to transfer files over the same
3691
connection used to communicate with GDB.  This is convenient for
3692
targets accessible through other means, e.g. GNU/Linux systems running
3693
`gdbserver' over a network interface.  For other targets, e.g. embedded
3694
devices with only a single serial port, this may be the only way to
3695
upload or download files.
3696
 
3697
   Not all remote targets support these commands.
3698
 
3699
`remote put HOSTFILE TARGETFILE'
3700
     Copy file HOSTFILE from the host system (the machine running GDB)
3701
     to TARGETFILE on the target system.
3702
 
3703
`remote get TARGETFILE HOSTFILE'
3704
     Copy file TARGETFILE from the target system to HOSTFILE on the
3705
     host system.
3706
 
3707
`remote delete TARGETFILE'
3708
     Delete TARGETFILE from the target system.
3709
 
3710
 
3711

3712
File: gdb.info,  Node: Server,  Next: Remote Configuration,  Prev: File Transfer,  Up: Remote Debugging
3713
 
3714
17.3 Using the `gdbserver' Program
3715
==================================
3716
 
3717
`gdbserver' is a control program for Unix-like systems, which allows
3718
you to connect your program with a remote GDB via `target remote'--but
3719
without linking in the usual debugging stub.
3720
 
3721
   `gdbserver' is not a complete replacement for the debugging stubs,
3722
because it requires essentially the same operating-system facilities
3723
that GDB itself does.  In fact, a system that can run `gdbserver' to
3724
connect to a remote GDB could also run GDB locally!  `gdbserver' is
3725
sometimes useful nevertheless, because it is a much smaller program
3726
than GDB itself.  It is also easier to port than all of GDB, so you may
3727
be able to get started more quickly on a new system by using
3728
`gdbserver'.  Finally, if you develop code for real-time systems, you
3729
may find that the tradeoffs involved in real-time operation make it
3730
more convenient to do as much development work as possible on another
3731
system, for example by cross-compiling.  You can use `gdbserver' to
3732
make a similar choice for debugging.
3733
 
3734
   GDB and `gdbserver' communicate via either a serial line or a TCP
3735
connection, using the standard GDB remote serial protocol.
3736
 
3737
     _Warning:_ `gdbserver' does not have any built-in security.  Do
3738
     not run `gdbserver' connected to any public network; a GDB
3739
     connection to `gdbserver' provides access to the target system
3740
     with the same privileges as the user running `gdbserver'.
3741
 
3742
17.3.1 Running `gdbserver'
3743
--------------------------
3744
 
3745
Run `gdbserver' on the target system.  You need a copy of the program
3746
you want to debug, including any libraries it requires.  `gdbserver'
3747
does not need your program's symbol table, so you can strip the program
3748
if necessary to save space.  GDB on the host system does all the symbol
3749
handling.
3750
 
3751
   To use the server, you must tell it how to communicate with GDB; the
3752
name of your program; and the arguments for your program.  The usual
3753
syntax is:
3754
 
3755
     target> gdbserver COMM PROGRAM [ ARGS ... ]
3756
 
3757
   COMM is either a device name (to use a serial line) or a TCP
3758
hostname and portnumber.  For example, to debug Emacs with the argument
3759
`foo.txt' and communicate with GDB over the serial port `/dev/com1':
3760
 
3761
     target> gdbserver /dev/com1 emacs foo.txt
3762
 
3763
   `gdbserver' waits passively for the host GDB to communicate with it.
3764
 
3765
   To use a TCP connection instead of a serial line:
3766
 
3767
     target> gdbserver host:2345 emacs foo.txt
3768
 
3769
   The only difference from the previous example is the first argument,
3770
specifying that you are communicating with the host GDB via TCP.  The
3771
`host:2345' argument means that `gdbserver' is to expect a TCP
3772
connection from machine `host' to local TCP port 2345.  (Currently, the
3773
`host' part is ignored.)  You can choose any number you want for the
3774
port number as long as it does not conflict with any TCP ports already
3775
in use on the target system (for example, `23' is reserved for
3776
`telnet').(1)  You must use the same port number with the host GDB
3777
`target remote' command.
3778
 
3779
17.3.1.1 Attaching to a Running Program
3780
.......................................
3781
 
3782
On some targets, `gdbserver' can also attach to running programs.  This
3783
is accomplished via the `--attach' argument.  The syntax is:
3784
 
3785
     target> gdbserver --attach COMM PID
3786
 
3787
   PID is the process ID of a currently running process.  It isn't
3788
necessary to point `gdbserver' at a binary for the running process.
3789
 
3790
   You can debug processes by name instead of process ID if your target
3791
has the `pidof' utility:
3792
 
3793
     target> gdbserver --attach COMM `pidof PROGRAM`
3794
 
3795
   In case more than one copy of PROGRAM is running, or PROGRAM has
3796
multiple threads, most versions of `pidof' support the `-s' option to
3797
only return the first process ID.
3798
 
3799
17.3.1.2 Multi-Process Mode for `gdbserver'
3800
...........................................
3801
 
3802
When you connect to `gdbserver' using `target remote', `gdbserver'
3803
debugs the specified program only once.  When the program exits, or you
3804
detach from it, GDB closes the connection and `gdbserver' exits.
3805
 
3806
   If you connect using `target extended-remote', `gdbserver' enters
3807
multi-process mode.  When the debugged program exits, or you detach
3808
from it, GDB stays connected to `gdbserver' even though no program is
3809
running.  The `run' and `attach' commands instruct `gdbserver' to run
3810
or attach to a new program.  The `run' command uses `set remote
3811
exec-file' (*note set remote exec-file::) to select the program to run.
3812
Command line arguments are supported, except for wildcard expansion
3813
and I/O redirection (*note Arguments::).
3814
 
3815
   To start `gdbserver' without supplying an initial command to run or
3816
process ID to attach, use the `--multi' command line option.  Then you
3817
can connect using `target extended-remote' and start the program you
3818
want to debug.
3819
 
3820
   `gdbserver' does not automatically exit in multi-process mode.  You
3821
can terminate it by using `monitor exit' (*note Monitor Commands for
3822
gdbserver::).
3823
 
3824
17.3.1.3 Other Command-Line Arguments for `gdbserver'
3825
.....................................................
3826
 
3827
You can include `--debug' on the `gdbserver' command line.  `gdbserver'
3828
will display extra status information about the debugging process.
3829
This option is intended for `gdbserver' development and for bug reports
3830
to the developers.
3831
 
3832
17.3.2 Connecting to `gdbserver'
3833
--------------------------------
3834
 
3835
Run GDB on the host system.
3836
 
3837
   First make sure you have the necessary symbol files.  Load symbols
3838
for your application using the `file' command before you connect.  Use
3839
`set sysroot' to locate target libraries (unless your GDB was compiled
3840
with the correct sysroot using `--with-sysroot').
3841
 
3842
   The symbol file and target libraries must exactly match the
3843
executable and libraries on the target, with one exception: the files
3844
on the host system should not be stripped, even if the files on the
3845
target system are.  Mismatched or missing files will lead to confusing
3846
results during debugging.  On GNU/Linux targets, mismatched or missing
3847
files may also prevent `gdbserver' from debugging multi-threaded
3848
programs.
3849
 
3850
   Connect to your target (*note Connecting to a Remote Target:
3851
Connecting.).  For TCP connections, you must start up `gdbserver' prior
3852
to using the `target remote' command.  Otherwise you may get an error
3853
whose text depends on the host system, but which usually looks
3854
something like `Connection refused'.  Don't use the `load' command in
3855
GDB when using `gdbserver', since the program is already on the target.
3856
 
3857
17.3.3 Monitor Commands for `gdbserver'
3858
---------------------------------------
3859
 
3860
During a GDB session using `gdbserver', you can use the `monitor'
3861
command to send special requests to `gdbserver'.  Here are the
3862
available commands.
3863
 
3864
`monitor help'
3865
     List the available monitor commands.
3866
 
3867
`monitor set debug 0'
3868
`monitor set debug 1'
3869
     Disable or enable general debugging messages.
3870
 
3871
`monitor set remote-debug 0'
3872
`monitor set remote-debug 1'
3873
     Disable or enable specific debugging messages associated with the
3874
     remote protocol (*note Remote Protocol::).
3875
 
3876
`monitor exit'
3877
     Tell gdbserver to exit immediately.  This command should be
3878
     followed by `disconnect' to close the debugging session.
3879
     `gdbserver' will detach from any attached processes and kill any
3880
     processes it created.  Use `monitor exit' to terminate `gdbserver'
3881
     at the end of a multi-process mode debug session.
3882
 
3883
 
3884
   ---------- Footnotes ----------
3885
 
3886
   (1) If you choose a port number that conflicts with another service,
3887
`gdbserver' prints an error message and exits.
3888
 
3889

3890
File: gdb.info,  Node: Remote Configuration,  Next: Remote Stub,  Prev: Server,  Up: Remote Debugging
3891
 
3892
17.4 Remote Configuration
3893
=========================
3894
 
3895
This section documents the configuration options available when
3896
debugging remote programs.  For the options related to the File I/O
3897
extensions of the remote protocol, see *Note system-call-allowed:
3898
system.
3899
 
3900
`set remoteaddresssize BITS'
3901
     Set the maximum size of address in a memory packet to the specified
3902
     number of bits.  GDB will mask off the address bits above that
3903
     number, when it passes addresses to the remote target.  The
3904
     default value is the number of bits in the target's address.
3905
 
3906
`show remoteaddresssize'
3907
     Show the current value of remote address size in bits.
3908
 
3909
`set remotebaud N'
3910
     Set the baud rate for the remote serial I/O to N baud.  The value
3911
     is used to set the speed of the serial port used for debugging
3912
     remote targets.
3913
 
3914
`show remotebaud'
3915
     Show the current speed of the remote connection.
3916
 
3917
`set remotebreak'
3918
     If set to on, GDB sends a `BREAK' signal to the remote when you
3919
     type `Ctrl-c' to interrupt the program running on the remote.  If
3920
     set to off, GDB sends the `Ctrl-C' character instead.  The default
3921
     is off, since most remote systems expect to see `Ctrl-C' as the
3922
     interrupt signal.
3923
 
3924
`show remotebreak'
3925
     Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote
3926
     program.
3927
 
3928
`set remoteflow on'
3929
`set remoteflow off'
3930
     Enable or disable hardware flow control (`RTS'/`CTS') on the
3931
     serial port used to communicate to the remote target.
3932
 
3933
`show remoteflow'
3934
     Show the current setting of hardware flow control.
3935
 
3936
`set remotelogbase BASE'
3937
     Set the base (a.k.a. radix) of logging serial protocol
3938
     communications to BASE.  Supported values of BASE are: `ascii',
3939
     `octal', and `hex'.  The default is `ascii'.
3940
 
3941
`show remotelogbase'
3942
     Show the current setting of the radix for logging remote serial
3943
     protocol.
3944
 
3945
`set remotelogfile FILE'
3946
     Record remote serial communications on the named FILE.  The
3947
     default is not to record at all.
3948
 
3949
`show remotelogfile.'
3950
     Show the current setting  of the file name on which to record the
3951
     serial communications.
3952
 
3953
`set remotetimeout NUM'
3954
     Set the timeout limit to wait for the remote target to respond to
3955
     NUM seconds.  The default is 2 seconds.
3956
 
3957
`show remotetimeout'
3958
     Show the current number of seconds to wait for the remote target
3959
     responses.
3960
 
3961
`set remote hardware-watchpoint-limit LIMIT'
3962
`set remote hardware-breakpoint-limit LIMIT'
3963
     Restrict GDB to using LIMIT remote hardware breakpoint or
3964
     watchpoints.  A limit of -1, the default, is treated as unlimited.
3965
 
3966
`set remote exec-file FILENAME'
3967
`show remote exec-file'
3968
     Select the file used for `run' with `target extended-remote'.
3969
     This should be set to a filename valid on the target system.  If
3970
     it is not set, the target will use a default filename (e.g. the
3971
     last program run).
3972
 
3973
   The GDB remote protocol autodetects the packets supported by your
3974
debugging stub.  If you need to override the autodetection, you can use
3975
these commands to enable or disable individual packets.  Each packet
3976
can be set to `on' (the remote target supports this packet), `off' (the
3977
remote target does not support this packet), or `auto' (detect remote
3978
target support for this packet).  They all default to `auto'.  For more
3979
information about each packet, see *Note Remote Protocol::.
3980
 
3981
   During normal use, you should not have to use any of these commands.
3982
If you do, that may be a bug in your remote debugging stub, or a bug in
3983
GDB.  You may want to report the problem to the GDB developers.
3984
 
3985
   For each packet NAME, the command to enable or disable the packet is
3986
`set remote NAME-packet'.  The available settings are:
3987
 
3988
Command Name         Remote Packet           Related Features
3989
`fetch-register'     `p'                     `info registers'
3990
`set-register'       `P'                     `set'
3991
`binary-download'    `X'                     `load', `set'
3992
`read-aux-vector'    `qXfer:auxv:read'       `info auxv'
3993
`symbol-lookup'      `qSymbol'               Detecting
3994
                                             multiple threads
3995
`attach'             `vAttach'               `attach'
3996
`verbose-resume'     `vCont'                 Stepping or
3997
                                             resuming multiple
3998
                                             threads
3999
`run'                `vRun'                  `run'
4000
`software-breakpoint'`Z0'                    `break'
4001
`hardware-breakpoint'`Z1'                    `hbreak'
4002
`write-watchpoint'   `Z2'                    `watch'
4003
`read-watchpoint'    `Z3'                    `rwatch'
4004
`access-watchpoint'  `Z4'                    `awatch'
4005
`target-features'    `qXfer:features:read'   `set architecture'
4006
`library-info'       `qXfer:libraries:read'  `info
4007
                                             sharedlibrary'
4008
`memory-map'         `qXfer:memory-map:read' `info mem'
4009
`read-spu-object'    `qXfer:spu:read'        `info spu'
4010
`write-spu-object'   `qXfer:spu:write'       `info spu'
4011
`get-thread-local-   `qGetTLSAddr'           Displaying
4012
storage-address'                             `__thread'
4013
                                             variables
4014
`supported-packets'  `qSupported'            Remote
4015
                                             communications
4016
                                             parameters
4017
`pass-signals'       `QPassSignals'          `handle SIGNAL'
4018
`hostio-close-packet'`vFile:close'           `remote get',
4019
                                             `remote put'
4020
`hostio-open-packet' `vFile:open'            `remote get',
4021
                                             `remote put'
4022
`hostio-pread-packet'`vFile:pread'           `remote get',
4023
                                             `remote put'
4024
`hostio-pwrite-packet'`vFile:pwrite'          `remote get',
4025
                                             `remote put'
4026
`hostio-unlink-packet'`vFile:unlink'          `remote delete'
4027
 
4028

4029
File: gdb.info,  Node: Remote Stub,  Prev: Remote Configuration,  Up: Remote Debugging
4030
 
4031
17.5 Implementing a Remote Stub
4032
===============================
4033
 
4034
The stub files provided with GDB implement the target side of the
4035
communication protocol, and the GDB side is implemented in the GDB
4036
source file `remote.c'.  Normally, you can simply allow these
4037
subroutines to communicate, and ignore the details.  (If you're
4038
implementing your own stub file, you can still ignore the details: start
4039
with one of the existing stub files.  `sparc-stub.c' is the best
4040
organized, and therefore the easiest to read.)
4041
 
4042
   To debug a program running on another machine (the debugging
4043
"target" machine), you must first arrange for all the usual
4044
prerequisites for the program to run by itself.  For example, for a C
4045
program, you need:
4046
 
4047
  1. A startup routine to set up the C runtime environment; these
4048
     usually have a name like `crt0'.  The startup routine may be
4049
     supplied by your hardware supplier, or you may have to write your
4050
     own.
4051
 
4052
  2. A C subroutine library to support your program's subroutine calls,
4053
     notably managing input and output.
4054
 
4055
  3. A way of getting your program to the other machine--for example, a
4056
     download program.  These are often supplied by the hardware
4057
     manufacturer, but you may have to write your own from hardware
4058
     documentation.
4059
 
4060
   The next step is to arrange for your program to use a serial port to
4061
communicate with the machine where GDB is running (the "host" machine).
4062
In general terms, the scheme looks like this:
4063
 
4064
_On the host,_
4065
     GDB already understands how to use this protocol; when everything
4066
     else is set up, you can simply use the `target remote' command
4067
     (*note Specifying a Debugging Target: Targets.).
4068
 
4069
_On the target,_
4070
     you must link with your program a few special-purpose subroutines
4071
     that implement the GDB remote serial protocol.  The file
4072
     containing these subroutines is called  a "debugging stub".
4073
 
4074
     On certain remote targets, you can use an auxiliary program
4075
     `gdbserver' instead of linking a stub into your program.  *Note
4076
     Using the `gdbserver' Program: Server, for details.
4077
 
4078
   The debugging stub is specific to the architecture of the remote
4079
machine; for example, use `sparc-stub.c' to debug programs on SPARC
4080
boards.
4081
 
4082
   These working remote stubs are distributed with GDB:
4083
 
4084
`i386-stub.c'
4085
     For Intel 386 and compatible architectures.
4086
 
4087
`m68k-stub.c'
4088
     For Motorola 680x0 architectures.
4089
 
4090
`sh-stub.c'
4091
     For Renesas SH architectures.
4092
 
4093
`sparc-stub.c'
4094
     For SPARC architectures.
4095
 
4096
`sparcl-stub.c'
4097
     For Fujitsu SPARCLITE architectures.
4098
 
4099
 
4100
   The `README' file in the GDB distribution may list other recently
4101
added stubs.
4102
 
4103
* Menu:
4104
 
4105
* Stub Contents::       What the stub can do for you
4106
* Bootstrapping::       What you must do for the stub
4107
* Debug Session::       Putting it all together
4108
 
4109

4110
File: gdb.info,  Node: Stub Contents,  Next: Bootstrapping,  Up: Remote Stub
4111
 
4112
17.5.1 What the Stub Can Do for You
4113
-----------------------------------
4114
 
4115
The debugging stub for your architecture supplies these three
4116
subroutines:
4117
 
4118
`set_debug_traps'
4119
     This routine arranges for `handle_exception' to run when your
4120
     program stops.  You must call this subroutine explicitly near the
4121
     beginning of your program.
4122
 
4123
`handle_exception'
4124
     This is the central workhorse, but your program never calls it
4125
     explicitly--the setup code arranges for `handle_exception' to run
4126
     when a trap is triggered.
4127
 
4128
     `handle_exception' takes control when your program stops during
4129
     execution (for example, on a breakpoint), and mediates
4130
     communications with GDB on the host machine.  This is where the
4131
     communications protocol is implemented; `handle_exception' acts as
4132
     the GDB representative on the target machine.  It begins by
4133
     sending summary information on the state of your program, then
4134
     continues to execute, retrieving and transmitting any information
4135
     GDB needs, until you execute a GDB command that makes your program
4136
     resume; at that point, `handle_exception' returns control to your
4137
     own code on the target machine.
4138
 
4139
`breakpoint'
4140
     Use this auxiliary subroutine to make your program contain a
4141
     breakpoint.  Depending on the particular situation, this may be
4142
     the only way for GDB to get control.  For instance, if your target
4143
     machine has some sort of interrupt button, you won't need to call
4144
     this; pressing the interrupt button transfers control to
4145
     `handle_exception'--in effect, to GDB.  On some machines, simply
4146
     receiving characters on the serial port may also trigger a trap;
4147
     again, in that situation, you don't need to call `breakpoint' from
4148
     your own program--simply running `target remote' from the host GDB
4149
     session gets control.
4150
 
4151
     Call `breakpoint' if none of these is true, or if you simply want
4152
     to make certain your program stops at a predetermined point for the
4153
     start of your debugging session.
4154
 
4155

4156
File: gdb.info,  Node: Bootstrapping,  Next: Debug Session,  Prev: Stub Contents,  Up: Remote Stub
4157
 
4158
17.5.2 What You Must Do for the Stub
4159
------------------------------------
4160
 
4161
The debugging stubs that come with GDB are set up for a particular chip
4162
architecture, but they have no information about the rest of your
4163
debugging target machine.
4164
 
4165
   First of all you need to tell the stub how to communicate with the
4166
serial port.
4167
 
4168
`int getDebugChar()'
4169
     Write this subroutine to read a single character from the serial
4170
     port.  It may be identical to `getchar' for your target system; a
4171
     different name is used to allow you to distinguish the two if you
4172
     wish.
4173
 
4174
`void putDebugChar(int)'
4175
     Write this subroutine to write a single character to the serial
4176
     port.  It may be identical to `putchar' for your target system; a
4177
     different name is used to allow you to distinguish the two if you
4178
     wish.
4179
 
4180
   If you want GDB to be able to stop your program while it is running,
4181
you need to use an interrupt-driven serial driver, and arrange for it
4182
to stop when it receives a `^C' (`\003', the control-C character).
4183
That is the character which GDB uses to tell the remote system to stop.
4184
 
4185
   Getting the debugging target to return the proper status to GDB
4186
probably requires changes to the standard stub; one quick and dirty way
4187
is to just execute a breakpoint instruction (the "dirty" part is that
4188
GDB reports a `SIGTRAP' instead of a `SIGINT').
4189
 
4190
   Other routines you need to supply are:
4191
 
4192
`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)'
4193
     Write this function to install EXCEPTION_ADDRESS in the exception
4194
     handling tables.  You need to do this because the stub does not
4195
     have any way of knowing what the exception handling tables on your
4196
     target system are like (for example, the processor's table might
4197
     be in ROM, containing entries which point to a table in RAM).
4198
     EXCEPTION_NUMBER is the exception number which should be changed;
4199
     its meaning is architecture-dependent (for example, different
4200
     numbers might represent divide by zero, misaligned access, etc).
4201
     When this exception occurs, control should be transferred directly
4202
     to EXCEPTION_ADDRESS, and the processor state (stack, registers,
4203
     and so on) should be just as it is when a processor exception
4204
     occurs.  So if you want to use a jump instruction to reach
4205
     EXCEPTION_ADDRESS, it should be a simple jump, not a jump to
4206
     subroutine.
4207
 
4208
     For the 386, EXCEPTION_ADDRESS should be installed as an interrupt
4209
     gate so that interrupts are masked while the handler runs.  The
4210
     gate should be at privilege level 0 (the most privileged level).
4211
     The SPARC and 68k stubs are able to mask interrupts themselves
4212
     without help from `exceptionHandler'.
4213
 
4214
`void flush_i_cache()'
4215
     On SPARC and SPARCLITE only, write this subroutine to flush the
4216
     instruction cache, if any, on your target machine.  If there is no
4217
     instruction cache, this subroutine may be a no-op.
4218
 
4219
     On target machines that have instruction caches, GDB requires this
4220
     function to make certain that the state of your program is stable.
4221
 
4222
You must also make sure this library routine is available:
4223
 
4224
`void *memset(void *, int, int)'
4225
     This is the standard library function `memset' that sets an area of
4226
     memory to a known value.  If you have one of the free versions of
4227
     `libc.a', `memset' can be found there; otherwise, you must either
4228
     obtain it from your hardware manufacturer, or write your own.
4229
 
4230
   If you do not use the GNU C compiler, you may need other standard
4231
library subroutines as well; this varies from one stub to another, but
4232
in general the stubs are likely to use any of the common library
4233
subroutines which `GCC' generates as inline code.
4234
 
4235

4236
File: gdb.info,  Node: Debug Session,  Prev: Bootstrapping,  Up: Remote Stub
4237
 
4238
17.5.3 Putting it All Together
4239
------------------------------
4240
 
4241
In summary, when your program is ready to debug, you must follow these
4242
steps.
4243
 
4244
  1. Make sure you have defined the supporting low-level routines
4245
     (*note What You Must Do for the Stub: Bootstrapping.):
4246
          `getDebugChar', `putDebugChar',
4247
          `flush_i_cache', `memset', `exceptionHandler'.
4248
 
4249
  2. Insert these lines near the top of your program:
4250
 
4251
          set_debug_traps();
4252
          breakpoint();
4253
 
4254
  3. For the 680x0 stub only, you need to provide a variable called
4255
     `exceptionHook'.  Normally you just use:
4256
 
4257
          void (*exceptionHook)() = 0;
4258
 
4259
     but if before calling `set_debug_traps', you set it to point to a
4260
     function in your program, that function is called when `GDB'
4261
     continues after stopping on a trap (for example, bus error).  The
4262
     function indicated by `exceptionHook' is called with one
4263
     parameter: an `int' which is the exception number.
4264
 
4265
  4. Compile and link together: your program, the GDB debugging stub for
4266
     your target architecture, and the supporting subroutines.
4267
 
4268
  5. Make sure you have a serial connection between your target machine
4269
     and the GDB host, and identify the serial port on the host.
4270
 
4271
  6. Download your program to your target machine (or get it there by
4272
     whatever means the manufacturer provides), and start it.
4273
 
4274
  7. Start GDB on the host, and connect to the target (*note Connecting
4275
     to a Remote Target: Connecting.).
4276
 
4277
 
4278

4279
File: gdb.info,  Node: Configurations,  Next: Controlling GDB,  Prev: Remote Debugging,  Up: Top
4280
 
4281
18 Configuration-Specific Information
4282
*************************************
4283
 
4284
While nearly all GDB commands are available for all native and cross
4285
versions of the debugger, there are some exceptions.  This chapter
4286
describes things that are only available in certain configurations.
4287
 
4288
   There are three major categories of configurations: native
4289
configurations, where the host and target are the same, embedded
4290
operating system configurations, which are usually the same for several
4291
different processor architectures, and bare embedded processors, which
4292
are quite different from each other.
4293
 
4294
* Menu:
4295
 
4296
* Native::
4297
* Embedded OS::
4298
* Embedded Processors::
4299
* Architectures::
4300
 
4301

4302
File: gdb.info,  Node: Native,  Next: Embedded OS,  Up: Configurations
4303
 
4304
18.1 Native
4305
===========
4306
 
4307
This section describes details specific to particular native
4308
configurations.
4309
 
4310
* Menu:
4311
 
4312
* HP-UX::                       HP-UX
4313
* BSD libkvm Interface::        Debugging BSD kernel memory images
4314
* SVR4 Process Information::    SVR4 process information
4315
* DJGPP Native::                Features specific to the DJGPP port
4316
* Cygwin Native::               Features specific to the Cygwin port
4317
* Hurd Native::                 Features specific to GNU Hurd
4318
* Neutrino::                    Features specific to QNX Neutrino
4319
 
4320

4321
File: gdb.info,  Node: HP-UX,  Next: BSD libkvm Interface,  Up: Native
4322
 
4323
18.1.1 HP-UX
4324
------------
4325
 
4326
On HP-UX systems, if you refer to a function or variable name that
4327
begins with a dollar sign, GDB searches for a user or system name
4328
first, before it searches for a convenience variable.
4329
 
4330

4331
File: gdb.info,  Node: BSD libkvm Interface,  Next: SVR4 Process Information,  Prev: HP-UX,  Up: Native
4332
 
4333
18.1.2 BSD libkvm Interface
4334
---------------------------
4335
 
4336
BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
4337
interface that provides a uniform interface for accessing kernel virtual
4338
memory images, including live systems and crash dumps.  GDB uses this
4339
interface to allow you to debug live kernels and kernel crash dumps on
4340
many native BSD configurations.  This is implemented as a special `kvm'
4341
debugging target.  For debugging a live system, load the currently
4342
running kernel into GDB and connect to the `kvm' target:
4343
 
4344
     (gdb) target kvm
4345
 
4346
   For debugging crash dumps, provide the file name of the crash dump
4347
as an argument:
4348
 
4349
     (gdb) target kvm /var/crash/bsd.0
4350
 
4351
   Once connected to the `kvm' target, the following commands are
4352
available:
4353
 
4354
`kvm pcb'
4355
     Set current context from the "Process Control Block" (PCB) address.
4356
 
4357
`kvm proc'
4358
     Set current context from proc address.  This command isn't
4359
     available on modern FreeBSD systems.
4360
 
4361

4362
File: gdb.info,  Node: SVR4 Process Information,  Next: DJGPP Native,  Prev: BSD libkvm Interface,  Up: Native
4363
 
4364
18.1.3 SVR4 Process Information
4365
-------------------------------
4366
 
4367
Many versions of SVR4 and compatible systems provide a facility called
4368
`/proc' that can be used to examine the image of a running process
4369
using file-system subroutines.  If GDB is configured for an operating
4370
system with this facility, the command `info proc' is available to
4371
report information about the process running your program, or about any
4372
process running on your system.  `info proc' works only on SVR4 systems
4373
that include the `procfs' code.  This includes, as of this writing,
4374
GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not
4375
HP-UX, for example.
4376
 
4377
`info proc'
4378
`info proc PROCESS-ID'
4379
     Summarize available information about any running process.  If a
4380
     process ID is specified by PROCESS-ID, display information about
4381
     that process; otherwise display information about the program being
4382
     debugged.  The summary includes the debugged process ID, the
4383
     command line used to invoke it, its current working directory, and
4384
     its executable file's absolute file name.
4385
 
4386
     On some systems, PROCESS-ID can be of the form `[PID]/TID' which
4387
     specifies a certain thread ID within a process.  If the optional
4388
     PID part is missing, it means a thread from the process being
4389
     debugged (the leading `/' still needs to be present, or else GDB
4390
     will interpret the number as a process ID rather than a thread ID).
4391
 
4392
`info proc mappings'
4393
     Report the memory address space ranges accessible in the program,
4394
     with information on whether the process has read, write, or
4395
     execute access rights to each range.  On GNU/Linux systems, each
4396
     memory range includes the object file which is mapped to that
4397
     range, instead of the memory access rights to that range.
4398
 
4399
`info proc stat'
4400
`info proc status'
4401
     These subcommands are specific to GNU/Linux systems.  They show
4402
     the process-related information, including the user ID and group
4403
     ID; how many threads are there in the process; its virtual memory
4404
     usage; the signals that are pending, blocked, and ignored; its
4405
     TTY; its consumption of system and user time; its stack size; its
4406
     `nice' value; etc.  For more information, see the `proc' man page
4407
     (type `man 5 proc' from your shell prompt).
4408
 
4409
`info proc all'
4410
     Show all the information about the process described under all of
4411
     the above `info proc' subcommands.
4412
 
4413
`set procfs-trace'
4414
     This command enables and disables tracing of `procfs' API calls.
4415
 
4416
`show procfs-trace'
4417
     Show the current state of `procfs' API call tracing.
4418
 
4419
`set procfs-file FILE'
4420
     Tell GDB to write `procfs' API trace to the named FILE.  GDB
4421
     appends the trace info to the previous contents of the file.  The
4422
     default is to display the trace on the standard output.
4423
 
4424
`show procfs-file'
4425
     Show the file to which `procfs' API trace is written.
4426
 
4427
`proc-trace-entry'
4428
`proc-trace-exit'
4429
`proc-untrace-entry'
4430
`proc-untrace-exit'
4431
     These commands enable and disable tracing of entries into and exits
4432
     from the `syscall' interface.
4433
 
4434
`info pidlist'
4435
     For QNX Neutrino only, this command displays the list of all the
4436
     processes and all the threads within each process.
4437
 
4438
`info meminfo'
4439
     For QNX Neutrino only, this command displays the list of all
4440
     mapinfos.
4441
 
4442

4443
File: gdb.info,  Node: DJGPP Native,  Next: Cygwin Native,  Prev: SVR4 Process Information,  Up: Native
4444
 
4445
18.1.4 Features for Debugging DJGPP Programs
4446
--------------------------------------------
4447
 
4448
DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows.
4449
DJGPP programs are 32-bit protected-mode programs that use the "DPMI"
4450
(DOS Protected-Mode Interface) API to run on top of real-mode DOS
4451
systems and their emulations.
4452
 
4453
   GDB supports native debugging of DJGPP programs, and defines a few
4454
commands specific to the DJGPP port.  This subsection describes those
4455
commands.
4456
 
4457
`info dos'
4458
     This is a prefix of DJGPP-specific commands which print
4459
     information about the target system and important OS structures.
4460
 
4461
`info dos sysinfo'
4462
     This command displays assorted information about the underlying
4463
     platform: the CPU type and features, the OS version and flavor, the
4464
     DPMI version, and the available conventional and DPMI memory.
4465
 
4466
`info dos gdt'
4467
`info dos ldt'
4468
`info dos idt'
4469
     These 3 commands display entries from, respectively, Global, Local,
4470
     and Interrupt Descriptor Tables (GDT, LDT, and IDT).  The
4471
     descriptor tables are data structures which store a descriptor for
4472
     each segment that is currently in use.  The segment's selector is
4473
     an index into a descriptor table; the table entry for that index
4474
     holds the descriptor's base address and limit, and its attributes
4475
     and access rights.
4476
 
4477
     A typical DJGPP program uses 3 segments: a code segment, a data
4478
     segment (used for both data and the stack), and a DOS segment
4479
     (which allows access to DOS/BIOS data structures and absolute
4480
     addresses in conventional memory).  However, the DPMI host will
4481
     usually define additional segments in order to support the DPMI
4482
     environment.
4483
 
4484
     These commands allow to display entries from the descriptor tables.
4485
     Without an argument, all entries from the specified table are
4486
     displayed.  An argument, which should be an integer expression,
4487
     means display a single entry whose index is given by the argument.
4488
     For example, here's a convenient way to display information about
4489
     the debugged program's data segment:
4490
 
4491
     `(gdb) info dos ldt $ds'
4492
     `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)'
4493
 
4494
 
4495
     This comes in handy when you want to see whether a pointer is
4496
     outside the data segment's limit (i.e. "garbled").
4497
 
4498
`info dos pde'
4499
`info dos pte'
4500
     These two commands display entries from, respectively, the Page
4501
     Directory and the Page Tables.  Page Directories and Page Tables
4502
     are data structures which control how virtual memory addresses are
4503
     mapped into physical addresses.  A Page Table includes an entry
4504
     for every page of memory that is mapped into the program's address
4505
     space; there may be several Page Tables, each one holding up to
4506
     4096 entries.  A Page Directory has up to 4096 entries, one each
4507
     for every Page Table that is currently in use.
4508
 
4509
     Without an argument, `info dos pde' displays the entire Page
4510
     Directory, and `info dos pte' displays all the entries in all of
4511
     the Page Tables.  An argument, an integer expression, given to the
4512
     `info dos pde' command means display only that entry from the Page
4513
     Directory table.  An argument given to the `info dos pte' command
4514
     means display entries from a single Page Table, the one pointed to
4515
     by the specified entry in the Page Directory.
4516
 
4517
     These commands are useful when your program uses "DMA" (Direct
4518
     Memory Access), which needs physical addresses to program the DMA
4519
     controller.
4520
 
4521
     These commands are supported only with some DPMI servers.
4522
 
4523
`info dos address-pte ADDR'
4524
     This command displays the Page Table entry for a specified linear
4525
     address.  The argument ADDR is a linear address which should
4526
     already have the appropriate segment's base address added to it,
4527
     because this command accepts addresses which may belong to _any_
4528
     segment.  For example, here's how to display the Page Table entry
4529
     for the page where a variable `i' is stored:
4530
 
4531
     `(gdb) info dos address-pte __djgpp_base_address + (char *)&i'
4532
     `Page Table entry for address 0x11a00d30:'
4533
     `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30'
4534
 
4535
 
4536
     This says that `i' is stored at offset `0xd30' from the page whose
4537
     physical base address is `0x02698000', and shows all the
4538
     attributes of that page.
4539
 
4540
     Note that you must cast the addresses of variables to a `char *',
4541
     since otherwise the value of `__djgpp_base_address', the base
4542
     address of all variables and functions in a DJGPP program, will be
4543
     added using the rules of C pointer arithmetics: if `i' is declared
4544
     an `int', GDB will add 4 times the value of `__djgpp_base_address'
4545
     to the address of `i'.
4546
 
4547
     Here's another example, it displays the Page Table entry for the
4548
     transfer buffer:
4549
 
4550
     `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)'
4551
     `Page Table entry for address 0x29110:'
4552
     `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110'
4553
 
4554
 
4555
     (The `+ 3' offset is because the transfer buffer's address is the
4556
     3rd member of the `_go32_info_block' structure.)  The output
4557
     clearly shows that this DPMI server maps the addresses in
4558
     conventional memory 1:1, i.e. the physical (`0x00029000' +
4559
     `0x110') and linear (`0x29110') addresses are identical.
4560
 
4561
     This command is supported only with some DPMI servers.
4562
 
4563
   In addition to native debugging, the DJGPP port supports remote
4564
debugging via a serial data link.  The following commands are specific
4565
to remote serial debugging in the DJGPP port of GDB.
4566
 
4567
`set com1base ADDR'
4568
     This command sets the base I/O port address of the `COM1' serial
4569
     port.
4570
 
4571
`set com1irq IRQ'
4572
     This command sets the "Interrupt Request" (`IRQ') line to use for
4573
     the `COM1' serial port.
4574
 
4575
     There are similar commands `set com2base', `set com3irq', etc. for
4576
     setting the port address and the `IRQ' lines for the other 3 COM
4577
     ports.
4578
 
4579
     The related commands `show com1base', `show com1irq' etc.  display
4580
     the current settings of the base address and the `IRQ' lines used
4581
     by the COM ports.
4582
 
4583
`info serial'
4584
     This command prints the status of the 4 DOS serial ports.  For each
4585
     port, it prints whether it's active or not, its I/O base address
4586
     and IRQ number, whether it uses a 16550-style FIFO, its baudrate,
4587
     and the counts of various errors encountered so far.
4588
 
4589

4590
File: gdb.info,  Node: Cygwin Native,  Next: Hurd Native,  Prev: DJGPP Native,  Up: Native
4591
 
4592
18.1.5 Features for Debugging MS Windows PE Executables
4593
-------------------------------------------------------
4594
 
4595
GDB supports native debugging of MS Windows programs, including DLLs
4596
with and without symbolic debugging information.  There are various
4597
additional Cygwin-specific commands, described in this section.
4598
Working with DLLs that have no debugging symbols is described in *Note
4599
Non-debug DLL Symbols::.
4600
 
4601
`info w32'
4602
     This is a prefix of MS Windows-specific commands which print
4603
     information about the target system and important OS structures.
4604
 
4605
`info w32 selector'
4606
     This command displays information returned by the Win32 API
4607
     `GetThreadSelectorEntry' function.  It takes an optional argument
4608
     that is evaluated to a long value to give the information about
4609
     this given selector.  Without argument, this command displays
4610
     information about the six segment registers.
4611
 
4612
`info dll'
4613
     This is a Cygwin-specific alias of `info shared'.
4614
 
4615
`dll-symbols'
4616
     This command loads symbols from a dll similarly to add-sym command
4617
     but without the need to specify a base address.
4618
 
4619
`set cygwin-exceptions MODE'
4620
     If MODE is `on', GDB will break on exceptions that happen inside
4621
     the Cygwin DLL.  If MODE is `off', GDB will delay recognition of
4622
     exceptions, and may ignore some exceptions which seem to be caused
4623
     by internal Cygwin DLL "bookkeeping".  This option is meant
4624
     primarily for debugging the Cygwin DLL itself; the default value
4625
     is `off' to avoid annoying GDB users with false `SIGSEGV' signals.
4626
 
4627
`show cygwin-exceptions'
4628
     Displays whether GDB will break on exceptions that happen inside
4629
     the Cygwin DLL itself.
4630
 
4631
`set new-console MODE'
4632
     If MODE is `on' the debuggee will be started in a new console on
4633
     next start.  If MODE is `off'i, the debuggee will be started in
4634
     the same console as the debugger.
4635
 
4636
`show new-console'
4637
     Displays whether a new console is used when the debuggee is
4638
     started.
4639
 
4640
`set new-group MODE'
4641
     This boolean value controls whether the debuggee should start a
4642
     new group or stay in the same group as the debugger.  This affects
4643
     the way the Windows OS handles `Ctrl-C'.
4644
 
4645
`show new-group'
4646
     Displays current value of new-group boolean.
4647
 
4648
`set debugevents'
4649
     This boolean value adds debug output concerning kernel events
4650
     related to the debuggee seen by the debugger.  This includes
4651
     events that signal thread and process creation and exit, DLL
4652
     loading and unloading, console interrupts, and debugging messages
4653
     produced by the Windows `OutputDebugString' API call.
4654
 
4655
`set debugexec'
4656
     This boolean value adds debug output concerning execute events
4657
     (such as resume thread) seen by the debugger.
4658
 
4659
`set debugexceptions'
4660
     This boolean value adds debug output concerning exceptions in the
4661
     debuggee seen by the debugger.
4662
 
4663
`set debugmemory'
4664
     This boolean value adds debug output concerning debuggee memory
4665
     reads and writes by the debugger.
4666
 
4667
`set shell'
4668
     This boolean values specifies whether the debuggee is called via a
4669
     shell or directly (default value is on).
4670
 
4671
`show shell'
4672
     Displays if the debuggee will be started with a shell.
4673
 
4674
 
4675
* Menu:
4676
 
4677
* Non-debug DLL Symbols::  Support for DLLs without debugging symbols
4678
 
4679

4680
File: gdb.info,  Node: Non-debug DLL Symbols,  Up: Cygwin Native
4681
 
4682
18.1.5.1 Support for DLLs without Debugging Symbols
4683
...................................................
4684
 
4685
Very often on windows, some of the DLLs that your program relies on do
4686
not include symbolic debugging information (for example,
4687
`kernel32.dll').  When GDB doesn't recognize any debugging symbols in a
4688
DLL, it relies on the minimal amount of symbolic information contained
4689
in the DLL's export table.  This section describes working with such
4690
symbols, known internally to GDB as "minimal symbols".
4691
 
4692
   Note that before the debugged program has started execution, no DLLs
4693
will have been loaded.  The easiest way around this problem is simply to
4694
start the program -- either by setting a breakpoint or letting the
4695
program run once to completion.  It is also possible to force GDB to
4696
load a particular DLL before starting the executable -- see the shared
4697
library information in *Note Files::, or the `dll-symbols' command in
4698
*Note Cygwin Native::.  Currently, explicitly loading symbols from a
4699
DLL with no debugging information will cause the symbol names to be
4700
duplicated in GDB's lookup table, which may adversely affect symbol
4701
lookup performance.
4702
 
4703
18.1.5.2 DLL Name Prefixes
4704
..........................
4705
 
4706
In keeping with the naming conventions used by the Microsoft debugging
4707
tools, DLL export symbols are made available with a prefix based on the
4708
DLL name, for instance `KERNEL32!CreateFileA'.  The plain name is also
4709
entered into the symbol table, so `CreateFileA' is often sufficient. In
4710
some cases there will be name clashes within a program (particularly if
4711
the executable itself includes full debugging symbols) necessitating
4712
the use of the fully qualified name when referring to the contents of
4713
the DLL. Use single-quotes around the name to avoid the exclamation
4714
mark ("!")  being interpreted as a language operator.
4715
 
4716
   Note that the internal name of the DLL may be all upper-case, even
4717
though the file name of the DLL is lower-case, or vice-versa. Since
4718
symbols within GDB are _case-sensitive_ this may cause some confusion.
4719
If in doubt, try the `info functions' and `info variables' commands or
4720
even `maint print msymbols' (*note Symbols::). Here's an example:
4721
 
4722
     (gdb) info function CreateFileA
4723
     All functions matching regular expression "CreateFileA":
4724
 
4725
     Non-debugging symbols:
4726
     0x77e885f4  CreateFileA
4727
     0x77e885f4  KERNEL32!CreateFileA
4728
 
4729
     (gdb) info function !
4730
     All functions matching regular expression "!":
4731
 
4732
     Non-debugging symbols:
4733
     0x6100114c  cygwin1!__assert
4734
     0x61004034  cygwin1!_dll_crt0@0
4735
     0x61004240  cygwin1!dll_crt0(per_process *)
4736
     [etc...]
4737
 
4738
18.1.5.3 Working with Minimal Symbols
4739
.....................................
4740
 
4741
Symbols extracted from a DLL's export table do not contain very much
4742
type information. All that GDB can do is guess whether a symbol refers
4743
to a function or variable depending on the linker section that contains
4744
the symbol. Also note that the actual contents of the memory contained
4745
in a DLL are not available unless the program is running. This means
4746
that you cannot examine the contents of a variable or disassemble a
4747
function within a DLL without a running program.
4748
 
4749
   Variables are generally treated as pointers and dereferenced
4750
automatically. For this reason, it is often necessary to prefix a
4751
variable name with the address-of operator ("&") and provide explicit
4752
type information in the command. Here's an example of the type of
4753
problem:
4754
 
4755
     (gdb) print 'cygwin1!__argv'
4756
     $1 = 268572168
4757
 
4758
     (gdb) x 'cygwin1!__argv'
4759
     0x10021610:      "\230y\""
4760
 
4761
   And two possible solutions:
4762
 
4763
     (gdb) print ((char **)'cygwin1!__argv')[0]
4764
     $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram"
4765
 
4766
     (gdb) x/2x &'cygwin1!__argv'
4767
     0x610c0aa8 :    0x10021608      0x00000000
4768
     (gdb) x/x 0x10021608
4769
     0x10021608:     0x0022fd98
4770
     (gdb) x/s 0x0022fd98
4771
     0x22fd98:        "/cygdrive/c/mydirectory/myprogram"
4772
 
4773
   Setting a break point within a DLL is possible even before the
4774
program starts execution. However, under these circumstances, GDB can't
4775
examine the initial instructions of the function in order to skip the
4776
function's frame set-up code. You can work around this by using "*&" to
4777
set the breakpoint at a raw memory address:
4778
 
4779
     (gdb) break *&'python22!PyOS_Readline'
4780
     Breakpoint 1 at 0x1e04eff0
4781
 
4782
   The author of these extensions is not entirely convinced that
4783
setting a break point within a shared DLL like `kernel32.dll' is
4784
completely safe.
4785
 
4786

4787
File: gdb.info,  Node: Hurd Native,  Next: Neutrino,  Prev: Cygwin Native,  Up: Native
4788
 
4789
18.1.6 Commands Specific to GNU Hurd Systems
4790
--------------------------------------------
4791
 
4792
This subsection describes GDB commands specific to the GNU Hurd native
4793
debugging.
4794
 
4795
`set signals'
4796
`set sigs'
4797
     This command toggles the state of inferior signal interception by
4798
     GDB.  Mach exceptions, such as breakpoint traps, are not affected
4799
     by this command.  `sigs' is a shorthand alias for `signals'.
4800
 
4801
`show signals'
4802
`show sigs'
4803
     Show the current state of intercepting inferior's signals.
4804
 
4805
`set signal-thread'
4806
`set sigthread'
4807
     This command tells GDB which thread is the `libc' signal thread.
4808
     That thread is run when a signal is delivered to a running
4809
     process.  `set sigthread' is the shorthand alias of `set
4810
     signal-thread'.
4811
 
4812
`show signal-thread'
4813
`show sigthread'
4814
     These two commands show which thread will run when the inferior is
4815
     delivered a signal.
4816
 
4817
`set stopped'
4818
     This commands tells GDB that the inferior process is stopped, as
4819
     with the `SIGSTOP' signal.  The stopped process can be continued
4820
     by delivering a signal to it.
4821
 
4822
`show stopped'
4823
     This command shows whether GDB thinks the debuggee is stopped.
4824
 
4825
`set exceptions'
4826
     Use this command to turn off trapping of exceptions in the
4827
     inferior.  When exception trapping is off, neither breakpoints nor
4828
     single-stepping will work.  To restore the default, set exception
4829
     trapping on.
4830
 
4831
`show exceptions'
4832
     Show the current state of trapping exceptions in the inferior.
4833
 
4834
`set task pause'
4835
     This command toggles task suspension when GDB has control.
4836
     Setting it to on takes effect immediately, and the task is
4837
     suspended whenever GDB gets control.  Setting it to off will take
4838
     effect the next time the inferior is continued.  If this option is
4839
     set to off, you can use `set thread default pause on' or `set
4840
     thread pause on' (see below) to pause individual threads.
4841
 
4842
`show task pause'
4843
     Show the current state of task suspension.
4844
 
4845
`set task detach-suspend-count'
4846
     This command sets the suspend count the task will be left with when
4847
     GDB detaches from it.
4848
 
4849
`show task detach-suspend-count'
4850
     Show the suspend count the task will be left with when detaching.
4851
 
4852
`set task exception-port'
4853
`set task excp'
4854
     This command sets the task exception port to which GDB will
4855
     forward exceptions.  The argument should be the value of the "send
4856
     rights" of the task.  `set task excp' is a shorthand alias.
4857
 
4858
`set noninvasive'
4859
     This command switches GDB to a mode that is the least invasive as
4860
     far as interfering with the inferior is concerned.  This is the
4861
     same as using `set task pause', `set exceptions', and `set
4862
     signals' to values opposite to the defaults.
4863
 
4864
`info send-rights'
4865
`info receive-rights'
4866
`info port-rights'
4867
`info port-sets'
4868
`info dead-names'
4869
`info ports'
4870
`info psets'
4871
     These commands display information about, respectively, send
4872
     rights, receive rights, port rights, port sets, and dead names of
4873
     a task.  There are also shorthand aliases: `info ports' for `info
4874
     port-rights' and `info psets' for `info port-sets'.
4875
 
4876
`set thread pause'
4877
     This command toggles current thread suspension when GDB has
4878
     control.  Setting it to on takes effect immediately, and the
4879
     current thread is suspended whenever GDB gets control.  Setting it
4880
     to off will take effect the next time the inferior is continued.
4881
     Normally, this command has no effect, since when GDB has control,
4882
     the whole task is suspended.  However, if you used `set task pause
4883
     off' (see above), this command comes in handy to suspend only the
4884
     current thread.
4885
 
4886
`show thread pause'
4887
     This command shows the state of current thread suspension.
4888
 
4889
`set thread run'
4890
     This command sets whether the current thread is allowed to run.
4891
 
4892
`show thread run'
4893
     Show whether the current thread is allowed to run.
4894
 
4895
`set thread detach-suspend-count'
4896
     This command sets the suspend count GDB will leave on a thread
4897
     when detaching.  This number is relative to the suspend count
4898
     found by GDB when it notices the thread; use `set thread
4899
     takeover-suspend-count' to force it to an absolute value.
4900
 
4901
`show thread detach-suspend-count'
4902
     Show the suspend count GDB will leave on the thread when detaching.
4903
 
4904
`set thread exception-port'
4905
`set thread excp'
4906
     Set the thread exception port to which to forward exceptions.  This
4907
     overrides the port set by `set task exception-port' (see above).
4908
     `set thread excp' is the shorthand alias.
4909
 
4910
`set thread takeover-suspend-count'
4911
     Normally, GDB's thread suspend counts are relative to the value
4912
     GDB finds when it notices each thread.  This command changes the
4913
     suspend counts to be absolute instead.
4914
 
4915
`set thread default'
4916
`show thread default'
4917
     Each of the above `set thread' commands has a `set thread default'
4918
     counterpart (e.g., `set thread default pause', `set thread default
4919
     exception-port', etc.).  The `thread default' variety of commands
4920
     sets the default thread properties for all threads; you can then
4921
     change the properties of individual threads with the non-default
4922
     commands.
4923
 
4924

4925
File: gdb.info,  Node: Neutrino,  Prev: Hurd Native,  Up: Native
4926
 
4927
18.1.7 QNX Neutrino
4928
-------------------
4929
 
4930
GDB provides the following commands specific to the QNX Neutrino target:
4931
 
4932
`set debug nto-debug'
4933
     When set to on, enables debugging messages specific to the QNX
4934
     Neutrino support.
4935
 
4936
`show debug nto-debug'
4937
     Show the current state of QNX Neutrino messages.
4938
 
4939

4940
File: gdb.info,  Node: Embedded OS,  Next: Embedded Processors,  Prev: Native,  Up: Configurations
4941
 
4942
18.2 Embedded Operating Systems
4943
===============================
4944
 
4945
This section describes configurations involving the debugging of
4946
embedded operating systems that are available for several different
4947
architectures.
4948
 
4949
* Menu:
4950
 
4951
* VxWorks::                     Using GDB with VxWorks
4952
 
4953
   GDB includes the ability to debug programs running on various
4954
real-time operating systems.
4955
 
4956

4957
File: gdb.info,  Node: VxWorks,  Up: Embedded OS
4958
 
4959
18.2.1 Using GDB with VxWorks
4960
-----------------------------
4961
 
4962
`target vxworks MACHINENAME'
4963
     A VxWorks system, attached via TCP/IP.  The argument MACHINENAME
4964
     is the target system's machine name or IP address.
4965
 
4966
 
4967
   On VxWorks, `load' links FILENAME dynamically on the current target
4968
system as well as adding its symbols in GDB.
4969
 
4970
   GDB enables developers to spawn and debug tasks running on networked
4971
VxWorks targets from a Unix host.  Already-running tasks spawned from
4972
the VxWorks shell can also be debugged.  GDB uses code that runs on
4973
both the Unix host and on the VxWorks target.  The program `gdb' is
4974
installed and executed on the Unix host.  (It may be installed with the
4975
name `vxgdb', to distinguish it from a GDB for debugging programs on
4976
the host itself.)
4977
 
4978
`VxWorks-timeout ARGS'
4979
     All VxWorks-based targets now support the option `vxworks-timeout'.
4980
     This option is set by the user, and  ARGS represents the number of
4981
     seconds GDB waits for responses to rpc's.  You might use this if
4982
     your VxWorks target is a slow software simulator or is on the far
4983
     side of a thin network line.
4984
 
4985
   The following information on connecting to VxWorks was current when
4986
this manual was produced; newer releases of VxWorks may use revised
4987
procedures.
4988
 
4989
   To use GDB with VxWorks, you must rebuild your VxWorks kernel to
4990
include the remote debugging interface routines in the VxWorks library
4991
`rdb.a'.  To do this, define `INCLUDE_RDB' in the VxWorks configuration
4992
file `configAll.h' and rebuild your VxWorks kernel.  The resulting
4993
kernel contains `rdb.a', and spawns the source debugging task
4994
`tRdbTask' when VxWorks is booted.  For more information on configuring
4995
and remaking VxWorks, see the manufacturer's manual.
4996
 
4997
   Once you have included `rdb.a' in your VxWorks system image and set
4998
your Unix execution search path to find GDB, you are ready to run GDB.
4999
From your Unix host, run `gdb' (or `vxgdb', depending on your
5000
installation).
5001
 
5002
   GDB comes up showing the prompt:
5003
 
5004
     (vxgdb)
5005
 
5006
* Menu:
5007
 
5008
* VxWorks Connection::          Connecting to VxWorks
5009
* VxWorks Download::            VxWorks download
5010
* VxWorks Attach::              Running tasks
5011
 
5012

5013
File: gdb.info,  Node: VxWorks Connection,  Next: VxWorks Download,  Up: VxWorks
5014
 
5015
18.2.1.1 Connecting to VxWorks
5016
..............................
5017
 
5018
The GDB command `target' lets you connect to a VxWorks target on the
5019
network.  To connect to a target whose host name is "`tt'", type:
5020
 
5021
     (vxgdb) target vxworks tt
5022
 
5023
   GDB displays messages like these:
5024
 
5025
     Attaching remote machine across net...
5026
     Connected to tt.
5027
 
5028
   GDB then attempts to read the symbol tables of any object modules
5029
loaded into the VxWorks target since it was last booted.  GDB locates
5030
these files by searching the directories listed in the command search
5031
path (*note Your Program's Environment: Environment.); if it fails to
5032
find an object file, it displays a message such as:
5033
 
5034
     prog.o: No such file or directory.
5035
 
5036
   When this happens, add the appropriate directory to the search path
5037
with the GDB command `path', and execute the `target' command again.
5038
 
5039

5040
File: gdb.info,  Node: VxWorks Download,  Next: VxWorks Attach,  Prev: VxWorks Connection,  Up: VxWorks
5041
 
5042
18.2.1.2 VxWorks Download
5043
.........................
5044
 
5045
If you have connected to the VxWorks target and you want to debug an
5046
object that has not yet been loaded, you can use the GDB `load' command
5047
to download a file from Unix to VxWorks incrementally.  The object file
5048
given as an argument to the `load' command is actually opened twice:
5049
first by the VxWorks target in order to download the code, then by GDB
5050
in order to read the symbol table.  This can lead to problems if the
5051
current working directories on the two systems differ.  If both systems
5052
have NFS mounted the same filesystems, you can avoid these problems by
5053
using absolute paths.  Otherwise, it is simplest to set the working
5054
directory on both systems to the directory in which the object file
5055
resides, and then to reference the file by its name, without any path.
5056
For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in
5057
VxWorks and in `HOSTPATH/vw/demo/rdb' on the host.  To load this
5058
program, type this on VxWorks:
5059
 
5060
     -> cd "VXPATH/vw/demo/rdb"
5061
 
5062
Then, in GDB, type:
5063
 
5064
     (vxgdb) cd HOSTPATH/vw/demo/rdb
5065
     (vxgdb) load prog.o
5066
 
5067
   GDB displays a response similar to this:
5068
 
5069
     Reading symbol data from wherever/vw/demo/rdb/prog.o... done.
5070
 
5071
   You can also use the `load' command to reload an object module after
5072
editing and recompiling the corresponding source file.  Note that this
5073
makes GDB delete all currently-defined breakpoints, auto-displays, and
5074
convenience variables, and to clear the value history.  (This is
5075
necessary in order to preserve the integrity of debugger's data
5076
structures that reference the target system's symbol table.)
5077
 
5078

5079
File: gdb.info,  Node: VxWorks Attach,  Prev: VxWorks Download,  Up: VxWorks
5080
 
5081
18.2.1.3 Running Tasks
5082
......................
5083
 
5084
You can also attach to an existing task using the `attach' command as
5085
follows:
5086
 
5087
     (vxgdb) attach TASK
5088
 
5089
where TASK is the VxWorks hexadecimal task ID.  The task can be running
5090
or suspended when you attach to it.  Running tasks are suspended at the
5091
time of attachment.
5092
 
5093

5094
File: gdb.info,  Node: Embedded Processors,  Next: Architectures,  Prev: Embedded OS,  Up: Configurations
5095
 
5096
18.3 Embedded Processors
5097
========================
5098
 
5099
This section goes into details specific to particular embedded
5100
configurations.
5101
 
5102
   Whenever a specific embedded processor has a simulator, GDB allows
5103
to send an arbitrary command to the simulator.
5104
 
5105
`sim COMMAND'
5106
     Send an arbitrary COMMAND string to the simulator.  Consult the
5107
     documentation for the specific simulator in use for information
5108
     about acceptable commands.
5109
 
5110
* Menu:
5111
 
5112
* ARM::                         ARM RDI
5113
* M32R/D::                      Renesas M32R/D
5114
* M68K::                        Motorola M68K
5115
* MIPS Embedded::               MIPS Embedded
5116
* OpenRISC 1000::               OpenRisc 1000
5117
* PA::                          HP PA Embedded
5118
* PowerPC Embedded::            PowerPC Embedded
5119
* Sparclet::                    Tsqware Sparclet
5120
* Sparclite::                   Fujitsu Sparclite
5121
* Z8000::                       Zilog Z8000
5122
* AVR::                         Atmel AVR
5123
* CRIS::                        CRIS
5124
* Super-H::                     Renesas Super-H
5125
 
5126

5127
File: gdb.info,  Node: ARM,  Next: M32R/D,  Up: Embedded Processors
5128
 
5129
18.3.1 ARM
5130
----------
5131
 
5132
`target rdi DEV'
5133
     ARM Angel monitor, via RDI library interface to ADP protocol.  You
5134
     may use this target to communicate with both boards running the
5135
     Angel monitor, or with the EmbeddedICE JTAG debug device.
5136
 
5137
`target rdp DEV'
5138
     ARM Demon monitor.
5139
 
5140
 
5141
   GDB provides the following ARM-specific commands:
5142
 
5143
`set arm disassembler'
5144
     This commands selects from a list of disassembly styles.  The
5145
     `"std"' style is the standard style.
5146
 
5147
`show arm disassembler'
5148
     Show the current disassembly style.
5149
 
5150
`set arm apcs32'
5151
     This command toggles ARM operation mode between 32-bit and 26-bit.
5152
 
5153
`show arm apcs32'
5154
     Display the current usage of the ARM 32-bit mode.
5155
 
5156
`set arm fpu FPUTYPE'
5157
     This command sets the ARM floating-point unit (FPU) type.  The
5158
     argument FPUTYPE can be one of these:
5159
 
5160
    `auto'
5161
          Determine the FPU type by querying the OS ABI.
5162
 
5163
    `softfpa'
5164
          Software FPU, with mixed-endian doubles on little-endian ARM
5165
          processors.
5166
 
5167
    `fpa'
5168
          GCC-compiled FPA co-processor.
5169
 
5170
    `softvfp'
5171
          Software FPU with pure-endian doubles.
5172
 
5173
    `vfp'
5174
          VFP co-processor.
5175
 
5176
`show arm fpu'
5177
     Show the current type of the FPU.
5178
 
5179
`set arm abi'
5180
     This command forces GDB to use the specified ABI.
5181
 
5182
`show arm abi'
5183
     Show the currently used ABI.
5184
 
5185
`set debug arm'
5186
     Toggle whether to display ARM-specific debugging messages from the
5187
     ARM target support subsystem.
5188
 
5189
`show debug arm'
5190
     Show whether ARM-specific debugging messages are enabled.
5191
 
5192
   The following commands are available when an ARM target is debugged
5193
using the RDI interface:
5194
 
5195
`rdilogfile [FILE]'
5196
     Set the filename for the ADP (Angel Debugger Protocol) packet log.
5197
     With an argument, sets the log file to the specified FILE.  With
5198
     no argument, show the current log file name.  The default log file
5199
     is `rdi.log'.
5200
 
5201
`rdilogenable [ARG]'
5202
     Control logging of ADP packets.  With an argument of 1 or `"yes"'
5203
     enables logging, with an argument 0 or `"no"' disables it.  With
5204
     no arguments displays the current setting.  When logging is
5205
     enabled, ADP packets exchanged between GDB and the RDI target
5206
     device are logged to a file.
5207
 
5208
`set rdiromatzero'
5209
     Tell GDB whether the target has ROM at address 0.  If on, vector
5210
     catching is disabled, so that zero address can be used.  If off
5211
     (the default), vector catching is enabled.  For this command to
5212
     take effect, it needs to be invoked prior to the `target rdi'
5213
     command.
5214
 
5215
`show rdiromatzero'
5216
     Show the current setting of ROM at zero address.
5217
 
5218
`set rdiheartbeat'
5219
     Enable or disable RDI heartbeat packets.  It is not recommended to
5220
     turn on this option, since it confuses ARM and EPI JTAG interface,
5221
     as well as the Angel monitor.
5222
 
5223
`show rdiheartbeat'
5224
     Show the setting of RDI heartbeat packets.
5225
 
5226

5227
File: gdb.info,  Node: M32R/D,  Next: M68K,  Prev: ARM,  Up: Embedded Processors
5228
 
5229
18.3.2 Renesas M32R/D and M32R/SDI
5230
----------------------------------
5231
 
5232
`target m32r DEV'
5233
     Renesas M32R/D ROM monitor.
5234
 
5235
`target m32rsdi DEV'
5236
     Renesas M32R SDI server, connected via parallel port to the board.
5237
 
5238
   The following GDB commands are specific to the M32R monitor:
5239
 
5240
`set download-path PATH'
5241
     Set the default path for finding downloadable SREC files.
5242
 
5243
`show download-path'
5244
     Show the default path for downloadable SREC files.
5245
 
5246
`set board-address ADDR'
5247
     Set the IP address for the M32R-EVA target board.
5248
 
5249
`show board-address'
5250
     Show the current IP address of the target board.
5251
 
5252
`set server-address ADDR'
5253
     Set the IP address for the download server, which is the GDB's
5254
     host machine.
5255
 
5256
`show server-address'
5257
     Display the IP address of the download server.
5258
 
5259
`upload [FILE]'
5260
     Upload the specified SREC FILE via the monitor's Ethernet upload
5261
     capability.  If no FILE argument is given, the current executable
5262
     file is uploaded.
5263
 
5264
`tload [FILE]'
5265
     Test the `upload' command.
5266
 
5267
   The following commands are available for M32R/SDI:
5268
 
5269
`sdireset'
5270
     This command resets the SDI connection.
5271
 
5272
`sdistatus'
5273
     This command shows the SDI connection status.
5274
 
5275
`debug_chaos'
5276
     Instructs the remote that M32R/Chaos debugging is to be used.
5277
 
5278
`use_debug_dma'
5279
     Instructs the remote to use the DEBUG_DMA method of accessing
5280
     memory.
5281
 
5282
`use_mon_code'
5283
     Instructs the remote to use the MON_CODE method of accessing
5284
     memory.
5285
 
5286
`use_ib_break'
5287
     Instructs the remote to set breakpoints by IB break.
5288
 
5289
`use_dbt_break'
5290
     Instructs the remote to set breakpoints by DBT.
5291
 
5292

5293
File: gdb.info,  Node: M68K,  Next: MIPS Embedded,  Prev: M32R/D,  Up: Embedded Processors
5294
 
5295
18.3.3 M68k
5296
-----------
5297
 
5298
The Motorola m68k configuration includes ColdFire support, and a target
5299
command for the following ROM monitor.
5300
 
5301
`target dbug DEV'
5302
     dBUG ROM monitor for Motorola ColdFire.
5303
 
5304
 
5305

5306
File: gdb.info,  Node: MIPS Embedded,  Next: OpenRISC 1000,  Prev: M68K,  Up: Embedded Processors
5307
 
5308
18.3.4 MIPS Embedded
5309
--------------------
5310
 
5311
GDB can use the MIPS remote debugging protocol to talk to a MIPS board
5312
attached to a serial line.  This is available when you configure GDB
5313
with `--target=mips-idt-ecoff'.
5314
 
5315
   Use these GDB commands to specify the connection to your target
5316
board:
5317
 
5318
`target mips PORT'
5319
     To run a program on the board, start up `gdb' with the name of
5320
     your program as the argument.  To connect to the board, use the
5321
     command `target mips PORT', where PORT is the name of the serial
5322
     port connected to the board.  If the program has not already been
5323
     downloaded to the board, you may use the `load' command to
5324
     download it.  You can then use all the usual GDB commands.
5325
 
5326
     For example, this sequence connects to the target board through a
5327
     serial port, and loads and runs a program called PROG through the
5328
     debugger:
5329
 
5330
          host$ gdb PROG
5331
          GDB is free software and ...
5332
          (gdb) target mips /dev/ttyb
5333
          (gdb) load PROG
5334
          (gdb) run
5335
 
5336
`target mips HOSTNAME:PORTNUMBER'
5337
     On some GDB host configurations, you can specify a TCP connection
5338
     (for instance, to a serial line managed by a terminal
5339
     concentrator) instead of a serial port, using the syntax
5340
     `HOSTNAME:PORTNUMBER'.
5341
 
5342
`target pmon PORT'
5343
     PMON ROM monitor.
5344
 
5345
`target ddb PORT'
5346
     NEC's DDB variant of PMON for Vr4300.
5347
 
5348
`target lsi PORT'
5349
     LSI variant of PMON.
5350
 
5351
`target r3900 DEV'
5352
     Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips.
5353
 
5354
`target array DEV'
5355
     Array Tech LSI33K RAID controller board.
5356
 
5357
 
5358
GDB also supports these special commands for MIPS targets:
5359
 
5360
`set mipsfpu double'
5361
`set mipsfpu single'
5362
`set mipsfpu none'
5363
`set mipsfpu auto'
5364
`show mipsfpu'
5365
     If your target board does not support the MIPS floating point
5366
     coprocessor, you should use the command `set mipsfpu none' (if you
5367
     need this, you may wish to put the command in your GDB init file).
5368
     This tells GDB how to find the return value of functions which
5369
     return floating point values.  It also allows GDB to avoid saving
5370
     the floating point registers when calling functions on the board.
5371
     If you are using a floating point coprocessor with only single
5372
     precision floating point support, as on the R4650 processor, use
5373
     the command `set mipsfpu single'.  The default double precision
5374
     floating point coprocessor may be selected using `set mipsfpu
5375
     double'.
5376
 
5377
     In previous versions the only choices were double precision or no
5378
     floating point, so `set mipsfpu on' will select double precision
5379
     and `set mipsfpu off' will select no floating point.
5380
 
5381
     As usual, you can inquire about the `mipsfpu' variable with `show
5382
     mipsfpu'.
5383
 
5384
`set timeout SECONDS'
5385
`set retransmit-timeout SECONDS'
5386
`show timeout'
5387
`show retransmit-timeout'
5388
     You can control the timeout used while waiting for a packet, in
5389
     the MIPS remote protocol, with the `set timeout SECONDS' command.
5390
     The default is 5 seconds.  Similarly, you can control the timeout
5391
     used while waiting for an acknowledgement of a packet with the `set
5392
     retransmit-timeout SECONDS' command.  The default is 3 seconds.
5393
     You can inspect both values with `show timeout' and `show
5394
     retransmit-timeout'.  (These commands are _only_ available when
5395
     GDB is configured for `--target=mips-idt-ecoff'.)
5396
 
5397
     The timeout set by `set timeout' does not apply when GDB is
5398
     waiting for your program to stop.  In that case, GDB waits forever
5399
     because it has no way of knowing how long the program is going to
5400
     run before stopping.
5401
 
5402
`set syn-garbage-limit NUM'
5403
     Limit the maximum number of characters GDB should ignore when it
5404
     tries to synchronize with the remote target.  The default is 10
5405
     characters.  Setting the limit to -1 means there's no limit.
5406
 
5407
`show syn-garbage-limit'
5408
     Show the current limit on the number of characters to ignore when
5409
     trying to synchronize with the remote system.
5410
 
5411
`set monitor-prompt PROMPT'
5412
     Tell GDB to expect the specified PROMPT string from the remote
5413
     monitor.  The default depends on the target:
5414
    pmon target
5415
          `PMON'
5416
 
5417
    ddb target
5418
          `NEC010'
5419
 
5420
    lsi target
5421
          `PMON>'
5422
 
5423
`show monitor-prompt'
5424
     Show the current strings GDB expects as the prompt from the remote
5425
     monitor.
5426
 
5427
`set monitor-warnings'
5428
     Enable or disable monitor warnings about hardware breakpoints.
5429
     This has effect only for the `lsi' target.  When on, GDB will
5430
     display warning messages whose codes are returned by the `lsi'
5431
     PMON monitor for breakpoint commands.
5432
 
5433
`show monitor-warnings'
5434
     Show the current setting of printing monitor warnings.
5435
 
5436
`pmon COMMAND'
5437
     This command allows sending an arbitrary COMMAND string to the
5438
     monitor.  The monitor must be in debug mode for this to work.
5439
 
5440

5441
File: gdb.info,  Node: OpenRISC 1000,  Next: PA,  Prev: MIPS Embedded,  Up: Embedded Processors
5442
 
5443
18.3.5 OpenRISC 1000
5444
--------------------
5445
 
5446
See OR1k Architecture document (`www.opencores.org') for more
5447
information about platform and commands.
5448
 
5449
`target jtag jtag://HOST:PORT'
5450
     Connects to remote JTAG server.  JTAG remote server can be either
5451
     an or1ksim or JTAG server, connected via parallel port to the
5452
     board.
5453
 
5454
     Example: `target jtag jtag://localhost:9999'
5455
 
5456
`or1ksim COMMAND'
5457
     If connected to `or1ksim' OpenRISC 1000 Architectural Simulator,
5458
     proprietary commands can be executed.
5459
 
5460
`info or1k spr'
5461
     Displays spr groups.
5462
 
5463
`info or1k spr GROUP'
5464
`info or1k spr GROUPNO'
5465
     Displays register names in selected group.
5466
 
5467
`info or1k spr GROUP REGISTER'
5468
`info or1k spr REGISTER'
5469
`info or1k spr GROUPNO REGISTERNO'
5470
`info or1k spr REGISTERNO'
5471
     Shows information about specified spr register.
5472
 
5473
`spr GROUP REGISTER VALUE'
5474
`spr REGISTER VALUE'
5475
`spr GROUPNO REGISTERNO VALUE'
5476
`spr REGISTERNO VALUE'
5477
     Writes VALUE to specified spr register.
5478
 
5479
   Some implementations of OpenRISC 1000 Architecture also have
5480
hardware trace.  It is very similar to GDB trace, except it does not
5481
interfere with normal program execution and is thus much faster.
5482
Hardware breakpoints/watchpoint triggers can be set using:
5483
`$LEA/$LDATA'
5484
     Load effective address/data
5485
 
5486
`$SEA/$SDATA'
5487
     Store effective address/data
5488
 
5489
`$AEA/$ADATA'
5490
     Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA)
5491
 
5492
`$FETCH'
5493
     Fetch data
5494
 
5495
   When triggered, it can capture low level data, like: `PC', `LSEA',
5496
`LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'.
5497
 
5498
   `htrace' commands:
5499
`hwatch CONDITIONAL'
5500
     Set hardware watchpoint on combination of Load/Store Effective
5501
     Address(es) or Data.  For example:
5502
 
5503
     `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) &&
5504
     ($SDATA >= 50)'
5505
 
5506
     `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) &&
5507
     ($SDATA >= 50)'
5508
 
5509
`htrace info'
5510
     Display information about current HW trace configuration.
5511
 
5512
`htrace trigger CONDITIONAL'
5513
     Set starting criteria for HW trace.
5514
 
5515
`htrace qualifier CONDITIONAL'
5516
     Set acquisition qualifier for HW trace.
5517
 
5518
`htrace stop CONDITIONAL'
5519
     Set HW trace stopping criteria.
5520
 
5521
`htrace record [DATA]*'
5522
     Selects the data to be recorded, when qualifier is met and HW
5523
     trace was triggered.
5524
 
5525
`htrace enable'
5526
`htrace disable'
5527
     Enables/disables the HW trace.
5528
 
5529
`htrace rewind [FILENAME]'
5530
     Clears currently recorded trace data.
5531
 
5532
     If filename is specified, new trace file is made and any newly
5533
     collected data will be written there.
5534
 
5535
`htrace print [START [LEN]]'
5536
     Prints trace buffer, using current record configuration.
5537
 
5538
`htrace mode continuous'
5539
     Set continuous trace mode.
5540
 
5541
`htrace mode suspend'
5542
     Set suspend trace mode.
5543
 
5544
 
5545

5546
File: gdb.info,  Node: PowerPC Embedded,  Next: Sparclet,  Prev: PA,  Up: Embedded Processors
5547
 
5548
18.3.6 PowerPC Embedded
5549
-----------------------
5550
 
5551
GDB provides the following PowerPC-specific commands:
5552
 
5553
`set powerpc soft-float'
5554
`show powerpc soft-float'
5555
     Force GDB to use (or not use) a software floating point calling
5556
     convention.  By default, GDB selects the calling convention based
5557
     on the selected architecture and the provided executable file.
5558
 
5559
`set powerpc vector-abi'
5560
`show powerpc vector-abi'
5561
     Force GDB to use the specified calling convention for vector
5562
     arguments and return values.  The valid options are `auto';
5563
     `generic', to avoid vector registers even if they are present;
5564
     `altivec', to use AltiVec registers; and `spe' to use SPE
5565
     registers.  By default, GDB selects the calling convention based
5566
     on the selected architecture and the provided executable file.
5567
 
5568
`target dink32 DEV'
5569
     DINK32 ROM monitor.
5570
 
5571
`target ppcbug DEV'
5572
 
5573
`target ppcbug1 DEV'
5574
     PPCBUG ROM monitor for PowerPC.
5575
 
5576
`target sds DEV'
5577
     SDS monitor, running on a PowerPC board (such as Motorola's ADS).
5578
 
5579
   The following commands specific to the SDS protocol are supported by
5580
GDB:
5581
 
5582
`set sdstimeout NSEC'
5583
     Set the timeout for SDS protocol reads to be NSEC seconds.  The
5584
     default is 2 seconds.
5585
 
5586
`show sdstimeout'
5587
     Show the current value of the SDS timeout.
5588
 
5589
`sds COMMAND'
5590
     Send the specified COMMAND string to the SDS monitor.
5591
 
5592

5593
File: gdb.info,  Node: PA,  Next: PowerPC Embedded,  Prev: OpenRISC 1000,  Up: Embedded Processors
5594
 
5595
18.3.7 HP PA Embedded
5596
---------------------
5597
 
5598
`target op50n DEV'
5599
     OP50N monitor, running on an OKI HPPA board.
5600
 
5601
`target w89k DEV'
5602
     W89K monitor, running on a Winbond HPPA board.
5603
 
5604
 
5605

5606
File: gdb.info,  Node: Sparclet,  Next: Sparclite,  Prev: PowerPC Embedded,  Up: Embedded Processors
5607
 
5608
18.3.8 Tsqware Sparclet
5609
-----------------------
5610
 
5611
GDB enables developers to debug tasks running on Sparclet targets from
5612
a Unix host.  GDB uses code that runs on both the Unix host and on the
5613
Sparclet target.  The program `gdb' is installed and executed on the
5614
Unix host.
5615
 
5616
`remotetimeout ARGS'
5617
     GDB supports the option `remotetimeout'.  This option is set by
5618
     the user, and  ARGS represents the number of seconds GDB waits for
5619
     responses.
5620
 
5621
   When compiling for debugging, include the options `-g' to get debug
5622
information and `-Ttext' to relocate the program to where you wish to
5623
load it on the target.  You may also want to add the options `-n' or
5624
`-N' in order to reduce the size of the sections.  Example:
5625
 
5626
     sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N
5627
 
5628
   You can use `objdump' to verify that the addresses are what you
5629
intended:
5630
 
5631
     sparclet-aout-objdump --headers --syms prog
5632
 
5633
   Once you have set your Unix execution search path to find GDB, you
5634
are ready to run GDB.  From your Unix host, run `gdb' (or
5635
`sparclet-aout-gdb', depending on your installation).
5636
 
5637
   GDB comes up showing the prompt:
5638
 
5639
     (gdbslet)
5640
 
5641
* Menu:
5642
 
5643
* Sparclet File::                Setting the file to debug
5644
* Sparclet Connection::          Connecting to Sparclet
5645
* Sparclet Download::            Sparclet download
5646
* Sparclet Execution::           Running and debugging
5647
 
5648

5649
File: gdb.info,  Node: Sparclet File,  Next: Sparclet Connection,  Up: Sparclet
5650
 
5651
18.3.8.1 Setting File to Debug
5652
..............................
5653
 
5654
The GDB command `file' lets you choose with program to debug.
5655
 
5656
     (gdbslet) file prog
5657
 
5658
   GDB then attempts to read the symbol table of `prog'.  GDB locates
5659
the file by searching the directories listed in the command search path.
5660
If the file was compiled with debug information (option `-g'), source
5661
files will be searched as well.  GDB locates the source files by
5662
searching the directories listed in the directory search path (*note
5663
Your Program's Environment: Environment.).  If it fails to find a file,
5664
it displays a message such as:
5665
 
5666
     prog: No such file or directory.
5667
 
5668
   When this happens, add the appropriate directories to the search
5669
paths with the GDB commands `path' and `dir', and execute the `target'
5670
command again.
5671
 
5672

5673
File: gdb.info,  Node: Sparclet Connection,  Next: Sparclet Download,  Prev: Sparclet File,  Up: Sparclet
5674
 
5675
18.3.8.2 Connecting to Sparclet
5676
...............................
5677
 
5678
The GDB command `target' lets you connect to a Sparclet target.  To
5679
connect to a target on serial port "`ttya'", type:
5680
 
5681
     (gdbslet) target sparclet /dev/ttya
5682
     Remote target sparclet connected to /dev/ttya
5683
     main () at ../prog.c:3
5684
 
5685
   GDB displays messages like these:
5686
 
5687
     Connected to ttya.
5688
 
5689

5690
File: gdb.info,  Node: Sparclet Download,  Next: Sparclet Execution,  Prev: Sparclet Connection,  Up: Sparclet
5691
 
5692
18.3.8.3 Sparclet Download
5693
..........................
5694
 
5695
Once connected to the Sparclet target, you can use the GDB `load'
5696
command to download the file from the host to the target.  The file
5697
name and load offset should be given as arguments to the `load' command.
5698
Since the file format is aout, the program must be loaded to the
5699
starting address.  You can use `objdump' to find out what this value
5700
is.  The load offset is an offset which is added to the VMA (virtual
5701
memory address) of each of the file's sections.  For instance, if the
5702
program `prog' was linked to text address 0x1201000, with data at
5703
0x12010160 and bss at 0x12010170, in GDB, type:
5704
 
5705
     (gdbslet) load prog 0x12010000
5706
     Loading section .text, size 0xdb0 vma 0x12010000
5707
 
5708
   If the code is loaded at a different address then what the program
5709
was linked to, you may need to use the `section' and `add-symbol-file'
5710
commands to tell GDB where to map the symbol table.
5711
 
5712

5713
File: gdb.info,  Node: Sparclet Execution,  Prev: Sparclet Download,  Up: Sparclet
5714
 
5715
18.3.8.4 Running and Debugging
5716
..............................
5717
 
5718
You can now begin debugging the task using GDB's execution control
5719
commands, `b', `step', `run', etc.  See the GDB manual for the list of
5720
commands.
5721
 
5722
     (gdbslet) b main
5723
     Breakpoint 1 at 0x12010000: file prog.c, line 3.
5724
     (gdbslet) run
5725
     Starting program: prog
5726
     Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3
5727
     3        char *symarg = 0;
5728
     (gdbslet) step
5729
     4        char *execarg = "hello!";
5730
     (gdbslet)
5731
 
5732

5733
File: gdb.info,  Node: Sparclite,  Next: Z8000,  Prev: Sparclet,  Up: Embedded Processors
5734
 
5735
18.3.9 Fujitsu Sparclite
5736
------------------------
5737
 
5738
`target sparclite DEV'
5739
     Fujitsu sparclite boards, used only for the purpose of loading.
5740
     You must use an additional command to debug the program.  For
5741
     example: target remote DEV using GDB standard remote protocol.
5742
 
5743
 
5744

5745
File: gdb.info,  Node: Z8000,  Next: AVR,  Prev: Sparclite,  Up: Embedded Processors
5746
 
5747
18.3.10 Zilog Z8000
5748
-------------------
5749
 
5750
When configured for debugging Zilog Z8000 targets, GDB includes a Z8000
5751
simulator.
5752
 
5753
   For the Z8000 family, `target sim' simulates either the Z8002 (the
5754
unsegmented variant of the Z8000 architecture) or the Z8001 (the
5755
segmented variant).  The simulator recognizes which architecture is
5756
appropriate by inspecting the object code.
5757
 
5758
`target sim ARGS'
5759
     Debug programs on a simulated CPU.  If the simulator supports setup
5760
     options, specify them via ARGS.
5761
 
5762
After specifying this target, you can debug programs for the simulated
5763
CPU in the same style as programs for your host computer; use the
5764
`file' command to load a new program image, the `run' command to run
5765
your program, and so on.
5766
 
5767
   As well as making available all the usual machine registers (*note
5768
Registers: Registers.), the Z8000 simulator provides three additional
5769
items of information as specially named registers:
5770
 
5771
`cycles'
5772
     Counts clock-ticks in the simulator.
5773
 
5774
`insts'
5775
     Counts instructions run in the simulator.
5776
 
5777
`time'
5778
     Execution time in 60ths of a second.
5779
 
5780
 
5781
   You can refer to these values in GDB expressions with the usual
5782
conventions; for example, `b fputc if $cycles>5000' sets a conditional
5783
breakpoint that suspends only after at least 5000 simulated clock ticks.
5784
 
5785

5786
File: gdb.info,  Node: AVR,  Next: CRIS,  Prev: Z8000,  Up: Embedded Processors
5787
 
5788
18.3.11 Atmel AVR
5789
-----------------
5790
 
5791
When configured for debugging the Atmel AVR, GDB supports the following
5792
AVR-specific commands:
5793
 
5794
`info io_registers'
5795
     This command displays information about the AVR I/O registers.  For
5796
     each register, GDB prints its number and value.
5797
 
5798

5799
File: gdb.info,  Node: CRIS,  Next: Super-H,  Prev: AVR,  Up: Embedded Processors
5800
 
5801
18.3.12 CRIS
5802
------------
5803
 
5804
When configured for debugging CRIS, GDB provides the following
5805
CRIS-specific commands:
5806
 
5807
`set cris-version VER'
5808
     Set the current CRIS version to VER, either `10' or `32'.  The
5809
     CRIS version affects register names and sizes.  This command is
5810
     useful in case autodetection of the CRIS version fails.
5811
 
5812
`show cris-version'
5813
     Show the current CRIS version.
5814
 
5815
`set cris-dwarf2-cfi'
5816
     Set the usage of DWARF-2 CFI for CRIS debugging.  The default is
5817
     `on'.  Change to `off' when using `gcc-cris' whose version is below
5818
     `R59'.
5819
 
5820
`show cris-dwarf2-cfi'
5821
     Show the current state of using DWARF-2 CFI.
5822
 
5823
`set cris-mode MODE'
5824
     Set the current CRIS mode to MODE.  It should only be changed when
5825
     debugging in guru mode, in which case it should be set to `guru'
5826
     (the default is `normal').
5827
 
5828
`show cris-mode'
5829
     Show the current CRIS mode.
5830
 
5831

5832
File: gdb.info,  Node: Super-H,  Prev: CRIS,  Up: Embedded Processors
5833
 
5834
18.3.13 Renesas Super-H
5835
-----------------------
5836
 
5837
For the Renesas Super-H processor, GDB provides these commands:
5838
 
5839
`regs'
5840
     Show the values of all Super-H registers.
5841
 
5842

5843
File: gdb.info,  Node: Architectures,  Prev: Embedded Processors,  Up: Configurations
5844
 
5845
18.4 Architectures
5846
==================
5847
 
5848
This section describes characteristics of architectures that affect all
5849
uses of GDB with the architecture, both native and cross.
5850
 
5851
* Menu:
5852
 
5853
* i386::
5854
* A29K::
5855
* Alpha::
5856
* MIPS::
5857
* HPPA::               HP PA architecture
5858
* SPU::                Cell Broadband Engine SPU architecture
5859
* PowerPC::
5860
 
5861

5862
File: gdb.info,  Node: i386,  Next: A29K,  Up: Architectures
5863
 
5864
18.4.1 x86 Architecture-specific Issues
5865
---------------------------------------
5866
 
5867
`set struct-convention MODE'
5868
     Set the convention used by the inferior to return `struct's and
5869
     `union's from functions to MODE.  Possible values of MODE are
5870
     `"pcc"', `"reg"', and `"default"' (the default).  `"default"' or
5871
     `"pcc"' means that `struct's are returned on the stack, while
5872
     `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4,
5873
     or 8 bytes will be returned in a register.
5874
 
5875
`show struct-convention'
5876
     Show the current setting of the convention to return `struct's
5877
     from functions.
5878
 
5879

5880
File: gdb.info,  Node: A29K,  Next: Alpha,  Prev: i386,  Up: Architectures
5881
 
5882
18.4.2 A29K
5883
-----------
5884
 
5885
`set rstack_high_address ADDRESS'
5886
     On AMD 29000 family processors, registers are saved in a separate
5887
     "register stack".  There is no way for GDB to determine the extent
5888
     of this stack.  Normally, GDB just assumes that the stack is
5889
     "large enough".  This may result in GDB referencing memory
5890
     locations that do not exist.  If necessary, you can get around
5891
     this problem by specifying the ending address of the register
5892
     stack with the `set rstack_high_address' command.  The argument
5893
     should be an address, which you probably want to precede with `0x'
5894
     to specify in hexadecimal.
5895
 
5896
`show rstack_high_address'
5897
     Display the current limit of the register stack, on AMD 29000
5898
     family processors.
5899
 
5900
 
5901

5902
File: gdb.info,  Node: Alpha,  Next: MIPS,  Prev: A29K,  Up: Architectures
5903
 
5904
18.4.3 Alpha
5905
------------
5906
 
5907
See the following section.
5908
 
5909

5910
File: gdb.info,  Node: MIPS,  Next: HPPA,  Prev: Alpha,  Up: Architectures
5911
 
5912
18.4.4 MIPS
5913
-----------
5914
 
5915
Alpha- and MIPS-based computers use an unusual stack frame, which
5916
sometimes requires GDB to search backward in the object code to find
5917
the beginning of a function.
5918
 
5919
   To improve response time (especially for embedded applications, where
5920
GDB may be restricted to a slow serial line for this search) you may
5921
want to limit the size of this search, using one of these commands:
5922
 
5923
`set heuristic-fence-post LIMIT'
5924
     Restrict GDB to examining at most LIMIT bytes in its search for
5925
     the beginning of a function.  A value of 0 (the default) means
5926
     there is no limit.  However, except for 0, the larger the limit
5927
     the more bytes `heuristic-fence-post' must search and therefore
5928
     the longer it takes to run.  You should only need to use this
5929
     command when debugging a stripped executable.
5930
 
5931
`show heuristic-fence-post'
5932
     Display the current limit.
5933
 
5934
These commands are available _only_ when GDB is configured for
5935
debugging programs on Alpha or MIPS processors.
5936
 
5937
   Several MIPS-specific commands are available when debugging MIPS
5938
programs:
5939
 
5940
`set mips abi ARG'
5941
     Tell GDB which MIPS ABI is used by the inferior.  Possible values
5942
     of ARG are:
5943
 
5944
    `auto'
5945
          The default ABI associated with the current binary (this is
5946
          the default).
5947
 
5948
    `o32'
5949
 
5950
    `o64'
5951
 
5952
    `n32'
5953
 
5954
    `n64'
5955
 
5956
    `eabi32'
5957
 
5958
    `eabi64'
5959
 
5960
    `auto'
5961
 
5962
`show mips abi'
5963
     Show the MIPS ABI used by GDB to debug the inferior.
5964
 
5965
`set mipsfpu'
5966
`show mipsfpu'
5967
     *Note set mipsfpu: MIPS Embedded.
5968
 
5969
`set mips mask-address ARG'
5970
     This command determines whether the most-significant 32 bits of
5971
     64-bit MIPS addresses are masked off.  The argument ARG can be
5972
     `on', `off', or `auto'.  The latter is the default setting, which
5973
     lets GDB determine the correct value.
5974
 
5975
`show mips mask-address'
5976
     Show whether the upper 32 bits of MIPS addresses are masked off or
5977
     not.
5978
 
5979
`set remote-mips64-transfers-32bit-regs'
5980
     This command controls compatibility with 64-bit MIPS targets that
5981
     transfer data in 32-bit quantities.  If you have an old MIPS 64
5982
     target that transfers 32 bits for some registers, like SR and FSR,
5983
     and 64 bits for other registers, set this option to `on'.
5984
 
5985
`show remote-mips64-transfers-32bit-regs'
5986
     Show the current setting of compatibility with older MIPS 64
5987
     targets.
5988
 
5989
`set debug mips'
5990
     This command turns on and off debugging messages for the
5991
     MIPS-specific target code in GDB.
5992
 
5993
`show debug mips'
5994
     Show the current setting of MIPS debugging messages.
5995
 
5996

5997
File: gdb.info,  Node: HPPA,  Next: SPU,  Prev: MIPS,  Up: Architectures
5998
 
5999
18.4.5 HPPA
6000
-----------
6001
 
6002
When GDB is debugging the HP PA architecture, it provides the following
6003
special commands:
6004
 
6005
`set debug hppa'
6006
     This command determines whether HPPA architecture-specific
6007
     debugging messages are to be displayed.
6008
 
6009
`show debug hppa'
6010
     Show whether HPPA debugging messages are displayed.
6011
 
6012
`maint print unwind ADDRESS'
6013
     This command displays the contents of the unwind table entry at the
6014
     given ADDRESS.
6015
 
6016
 
6017

6018
File: gdb.info,  Node: SPU,  Next: PowerPC,  Prev: HPPA,  Up: Architectures
6019
 
6020
18.4.6 Cell Broadband Engine SPU architecture
6021
---------------------------------------------
6022
 
6023
When GDB is debugging the Cell Broadband Engine SPU architecture, it
6024
provides the following special commands:
6025
 
6026
`info spu event'
6027
     Display SPU event facility status.  Shows current event mask and
6028
     pending event status.
6029
 
6030
`info spu signal'
6031
     Display SPU signal notification facility status.  Shows pending
6032
     signal-control word and signal notification mode of both signal
6033
     notification channels.
6034
 
6035
`info spu mailbox'
6036
     Display SPU mailbox facility status.  Shows all pending entries,
6037
     in order of processing, in each of the SPU Write Outbound, SPU
6038
     Write Outbound Interrupt, and SPU Read Inbound mailboxes.
6039
 
6040
`info spu dma'
6041
     Display MFC DMA status.  Shows all pending commands in the MFC DMA
6042
     queue.  For each entry, opcode, tag, class IDs, effective and
6043
     local store addresses and transfer size are shown.
6044
 
6045
`info spu proxydma'
6046
     Display MFC Proxy-DMA status.  Shows all pending commands in the
6047
     MFC Proxy-DMA queue.  For each entry, opcode, tag, class IDs,
6048
     effective and local store addresses and transfer size are shown.
6049
 
6050
 
6051

6052
File: gdb.info,  Node: PowerPC,  Prev: SPU,  Up: Architectures
6053
 
6054
18.4.7 PowerPC
6055
--------------
6056
 
6057
When GDB is debugging the PowerPC architecture, it provides a set of
6058
pseudo-registers to enable inspection of 128-bit wide Decimal Floating
6059
Point numbers stored in the floating point registers. These values must
6060
be stored in two consecutive registers, always starting at an even
6061
register like `f0' or `f2'.
6062
 
6063
   The pseudo-registers go from `$dl0' through `$dl15', and are formed
6064
by joining the even/odd register pairs `f0' and `f1' for `$dl0', `f2'
6065
and `f3' for `$dl1' and so on.
6066
 
6067

6068
File: gdb.info,  Node: Controlling GDB,  Next: Sequences,  Prev: Configurations,  Up: Top
6069
 
6070
19 Controlling GDB
6071
******************
6072
 
6073
You can alter the way GDB interacts with you by using the `set'
6074
command.  For commands controlling how GDB displays data, see *Note
6075
Print Settings: Print Settings.  Other settings are described here.
6076
 
6077
* Menu:
6078
 
6079
* Prompt::                      Prompt
6080
* Editing::                     Command editing
6081
* Command History::             Command history
6082
* Screen Size::                 Screen size
6083
* Numbers::                     Numbers
6084
* ABI::                         Configuring the current ABI
6085
* Messages/Warnings::           Optional warnings and messages
6086
* Debugging Output::            Optional messages about internal happenings
6087
 
6088

6089
File: gdb.info,  Node: Prompt,  Next: Editing,  Up: Controlling GDB
6090
 
6091
19.1 Prompt
6092
===========
6093
 
6094
GDB indicates its readiness to read a command by printing a string
6095
called the "prompt".  This string is normally `(gdb)'.  You can change
6096
the prompt string with the `set prompt' command.  For instance, when
6097
debugging GDB with GDB, it is useful to change the prompt in one of the
6098
GDB sessions so that you can always tell which one you are talking to.
6099
 
6100
   _Note:_  `set prompt' does not add a space for you after the prompt
6101
you set.  This allows you to set a prompt which ends in a space or a
6102
prompt that does not.
6103
 
6104
`set prompt NEWPROMPT'
6105
     Directs GDB to use NEWPROMPT as its prompt string henceforth.
6106
 
6107
`show prompt'
6108
     Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT'
6109
 
6110

6111
File: gdb.info,  Node: Editing,  Next: Command History,  Prev: Prompt,  Up: Controlling GDB
6112
 
6113
19.2 Command Editing
6114
====================
6115
 
6116
GDB reads its input commands via the "Readline" interface.  This GNU
6117
library provides consistent behavior for programs which provide a
6118
command line interface to the user.  Advantages are GNU Emacs-style or
6119
"vi"-style inline editing of commands, `csh'-like history substitution,
6120
and a storage and recall of command history across debugging sessions.
6121
 
6122
   You may control the behavior of command line editing in GDB with the
6123
command `set'.
6124
 
6125
`set editing'
6126
`set editing on'
6127
     Enable command line editing (enabled by default).
6128
 
6129
`set editing off'
6130
     Disable command line editing.
6131
 
6132
`show editing'
6133
     Show whether command line editing is enabled.
6134
 
6135
   *Note Command Line Editing::, for more details about the Readline
6136
interface.  Users unfamiliar with GNU Emacs or `vi' are encouraged to
6137
read that chapter.
6138
 
6139

6140
File: gdb.info,  Node: Command History,  Next: Screen Size,  Prev: Editing,  Up: Controlling GDB
6141
 
6142
19.3 Command History
6143
====================
6144
 
6145
GDB can keep track of the commands you type during your debugging
6146
sessions, so that you can be certain of precisely what happened.  Use
6147
these commands to manage the GDB command history facility.
6148
 
6149
   GDB uses the GNU History library, a part of the Readline package, to
6150
provide the history facility.  *Note Using History Interactively::, for
6151
the detailed description of the History library.
6152
 
6153
   To issue a command to GDB without affecting certain aspects of the
6154
state which is seen by users, prefix it with `server ' (*note Server
6155
Prefix::).  This means that this command will not affect the command
6156
history, nor will it affect GDB's notion of which command to repeat if
6157
 is pressed on a line by itself.
6158
 
6159
   The server prefix does not affect the recording of values into the
6160
value history; to print a value without recording it into the value
6161
history, use the `output' command instead of the `print' command.
6162
 
6163
   Here is the description of GDB commands related to command history.
6164
 
6165
`set history filename FNAME'
6166
     Set the name of the GDB command history file to FNAME.  This is
6167
     the file where GDB reads an initial command history list, and
6168
     where it writes the command history from this session when it
6169
     exits.  You can access this list through history expansion or
6170
     through the history command editing characters listed below.  This
6171
     file defaults to the value of the environment variable
6172
     `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS)
6173
     if this variable is not set.
6174
 
6175
`set history save'
6176
`set history save on'
6177
     Record command history in a file, whose name may be specified with
6178
     the `set history filename' command.  By default, this option is
6179
     disabled.
6180
 
6181
`set history save off'
6182
     Stop recording command history in a file.
6183
 
6184
`set history size SIZE'
6185
     Set the number of commands which GDB keeps in its history list.
6186
     This defaults to the value of the environment variable `HISTSIZE',
6187
     or to 256 if this variable is not set.
6188
 
6189
   History expansion assigns special meaning to the character `!'.
6190
*Note Event Designators::, for more details.
6191
 
6192
   Since `!' is also the logical not operator in C, history expansion
6193
is off by default. If you decide to enable history expansion with the
6194
`set history expansion on' command, you may sometimes need to follow
6195
`!' (when it is used as logical not, in an expression) with a space or
6196
a tab to prevent it from being expanded.  The readline history
6197
facilities do not attempt substitution on the strings `!=' and `!(',
6198
even when history expansion is enabled.
6199
 
6200
   The commands to control history expansion are:
6201
 
6202
`set history expansion on'
6203
`set history expansion'
6204
     Enable history expansion.  History expansion is off by default.
6205
 
6206
`set history expansion off'
6207
     Disable history expansion.
6208
 
6209
`show history'
6210
`show history filename'
6211
`show history save'
6212
`show history size'
6213
`show history expansion'
6214
     These commands display the state of the GDB history parameters.
6215
     `show history' by itself displays all four states.
6216
 
6217
`show commands'
6218
     Display the last ten commands in the command history.
6219
 
6220
`show commands N'
6221
     Print ten commands centered on command number N.
6222
 
6223
`show commands +'
6224
     Print ten commands just after the commands last printed.
6225
 
6226

6227
File: gdb.info,  Node: Screen Size,  Next: Numbers,  Prev: Command History,  Up: Controlling GDB
6228
 
6229
19.4 Screen Size
6230
================
6231
 
6232
Certain commands to GDB may produce large amounts of information output
6233
to the screen.  To help you read all of it, GDB pauses and asks you for
6234
input at the end of each page of output.  Type  when you want to
6235
continue the output, or `q' to discard the remaining output.  Also, the
6236
screen width setting determines when to wrap lines of output.
6237
Depending on what is being printed, GDB tries to break the line at a
6238
readable place, rather than simply letting it overflow onto the
6239
following line.
6240
 
6241
   Normally GDB knows the size of the screen from the terminal driver
6242
software.  For example, on Unix GDB uses the termcap data base together
6243
with the value of the `TERM' environment variable and the `stty rows'
6244
and `stty cols' settings.  If this is not correct, you can override it
6245
with the `set height' and `set width' commands:
6246
 
6247
`set height LPP'
6248
`show height'
6249
`set width CPL'
6250
`show width'
6251
     These `set' commands specify a screen height of LPP lines and a
6252
     screen width of CPL characters.  The associated `show' commands
6253
     display the current settings.
6254
 
6255
     If you specify a height of zero lines, GDB does not pause during
6256
     output no matter how long the output is.  This is useful if output
6257
     is to a file or to an editor buffer.
6258
 
6259
     Likewise, you can specify `set width 0' to prevent GDB from
6260
     wrapping its output.
6261
 
6262
`set pagination on'
6263
`set pagination off'
6264
     Turn the output pagination on or off; the default is on.  Turning
6265
     pagination off is the alternative to `set height 0'.
6266
 
6267
`show pagination'
6268
     Show the current pagination mode.
6269
 
6270

6271
File: gdb.info,  Node: Numbers,  Next: ABI,  Prev: Screen Size,  Up: Controlling GDB
6272
 
6273
19.5 Numbers
6274
============
6275
 
6276
You can always enter numbers in octal, decimal, or hexadecimal in GDB
6277
by the usual conventions: octal numbers begin with `0', decimal numbers
6278
end with `.', and hexadecimal numbers begin with `0x'.  Numbers that
6279
neither begin with `0' or `0x', nor end with a `.' are, by default,
6280
entered in base 10; likewise, the default display for numbers--when no
6281
particular format is specified--is base 10.  You can change the default
6282
base for both input and output with the commands described below.
6283
 
6284
`set input-radix BASE'
6285
     Set the default base for numeric input.  Supported choices for
6286
     BASE are decimal 8, 10, or 16.  BASE must itself be specified
6287
     either unambiguously or using the current input radix; for
6288
     example, any of
6289
 
6290
          set input-radix 012
6291
          set input-radix 10.
6292
          set input-radix 0xa
6293
 
6294
     sets the input base to decimal.  On the other hand, `set
6295
     input-radix 10' leaves the input radix unchanged, no matter what
6296
     it was, since `10', being without any leading or trailing signs of
6297
     its base, is interpreted in the current radix.  Thus, if the
6298
     current radix is 16, `10' is interpreted in hex, i.e. as 16
6299
     decimal, which doesn't change the radix.
6300
 
6301
`set output-radix BASE'
6302
     Set the default base for numeric display.  Supported choices for
6303
     BASE are decimal 8, 10, or 16.  BASE must itself be specified
6304
     either unambiguously or using the current input radix.
6305
 
6306
`show input-radix'
6307
     Display the current default base for numeric input.
6308
 
6309
`show output-radix'
6310
     Display the current default base for numeric display.
6311
 
6312
`set radix [BASE]'
6313
`show radix'
6314
     These commands set and show the default base for both input and
6315
     output of numbers.  `set radix' sets the radix of input and output
6316
     to the same base; without an argument, it resets the radix back to
6317
     its default value of 10.
6318
 
6319
 
6320

6321
File: gdb.info,  Node: ABI,  Next: Messages/Warnings,  Prev: Numbers,  Up: Controlling GDB
6322
 
6323
19.6 Configuring the Current ABI
6324
================================
6325
 
6326
GDB can determine the "ABI" (Application Binary Interface) of your
6327
application automatically.  However, sometimes you need to override its
6328
conclusions.  Use these commands to manage GDB's view of the current
6329
ABI.
6330
 
6331
   One GDB configuration can debug binaries for multiple operating
6332
system targets, either via remote debugging or native emulation.  GDB
6333
will autodetect the "OS ABI" (Operating System ABI) in use, but you can
6334
override its conclusion using the `set osabi' command.  One example
6335
where this is useful is in debugging of binaries which use an alternate
6336
C library (e.g. UCLIBC for GNU/Linux) which does not have the same
6337
identifying marks that the standard C library for your platform
6338
provides.
6339
 
6340
`show osabi'
6341
     Show the OS ABI currently in use.
6342
 
6343
`set osabi'
6344
     With no argument, show the list of registered available OS ABI's.
6345
 
6346
`set osabi ABI'
6347
     Set the current OS ABI to ABI.
6348
 
6349
   Generally, the way that an argument of type `float' is passed to a
6350
function depends on whether the function is prototyped.  For a
6351
prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed
6352
unchanged, according to the architecture's convention for `float'.  For
6353
unprototyped (i.e. K&R style) functions, `float' arguments are first
6354
promoted to type `double' and then passed.
6355
 
6356
   Unfortunately, some forms of debug information do not reliably
6357
indicate whether a function is prototyped.  If GDB calls a function
6358
that is not marked as prototyped, it consults `set
6359
coerce-float-to-double'.
6360
 
6361
`set coerce-float-to-double'
6362
`set coerce-float-to-double on'
6363
     Arguments of type `float' will be promoted to `double' when passed
6364
     to an unprototyped function.  This is the default setting.
6365
 
6366
`set coerce-float-to-double off'
6367
     Arguments of type `float' will be passed directly to unprototyped
6368
     functions.
6369
 
6370
`show coerce-float-to-double'
6371
     Show the current setting of promoting `float' to `double'.
6372
 
6373
   GDB needs to know the ABI used for your program's C++ objects.  The
6374
correct C++ ABI depends on which C++ compiler was used to build your
6375
application.  GDB only fully supports programs with a single C++ ABI;
6376
if your program contains code using multiple C++ ABI's or if GDB can
6377
not identify your program's ABI correctly, you can tell GDB which ABI
6378
to use.  Currently supported ABI's include "gnu-v2", for `g++' versions
6379
before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for
6380
the HP ANSI C++ compiler.  Other C++ compilers may use the "gnu-v2" or
6381
"gnu-v3" ABI's as well.  The default setting is "auto".
6382
 
6383
`show cp-abi'
6384
     Show the C++ ABI currently in use.
6385
 
6386
`set cp-abi'
6387
     With no argument, show the list of supported C++ ABI's.
6388
 
6389
`set cp-abi ABI'
6390
`set cp-abi auto'
6391
     Set the current C++ ABI to ABI, or return to automatic detection.
6392
 
6393

6394
File: gdb.info,  Node: Messages/Warnings,  Next: Debugging Output,  Prev: ABI,  Up: Controlling GDB
6395
 
6396
19.7 Optional Warnings and Messages
6397
===================================
6398
 
6399
By default, GDB is silent about its inner workings.  If you are running
6400
on a slow machine, you may want to use the `set verbose' command.  This
6401
makes GDB tell you when it does a lengthy internal operation, so you
6402
will not think it has crashed.
6403
 
6404
   Currently, the messages controlled by `set verbose' are those which
6405
announce that the symbol table for a source file is being read; see
6406
`symbol-file' in *Note Commands to Specify Files: Files.
6407
 
6408
`set verbose on'
6409
     Enables GDB output of certain informational messages.
6410
 
6411
`set verbose off'
6412
     Disables GDB output of certain informational messages.
6413
 
6414
`show verbose'
6415
     Displays whether `set verbose' is on or off.
6416
 
6417
   By default, if GDB encounters bugs in the symbol table of an object
6418
file, it is silent; but if you are debugging a compiler, you may find
6419
this information useful (*note Errors Reading Symbol Files: Symbol
6420
Errors.).
6421
 
6422
`set complaints LIMIT'
6423
     Permits GDB to output LIMIT complaints about each type of unusual
6424
     symbols before becoming silent about the problem.  Set LIMIT to
6425
     zero to suppress all complaints; set it to a large number to
6426
     prevent complaints from being suppressed.
6427
 
6428
`show complaints'
6429
     Displays how many symbol complaints GDB is permitted to produce.
6430
 
6431
 
6432
   By default, GDB is cautious, and asks what sometimes seems to be a
6433
lot of stupid questions to confirm certain commands.  For example, if
6434
you try to run a program which is already running:
6435
 
6436
     (gdb) run
6437
     The program being debugged has been started already.
6438
     Start it from the beginning? (y or n)
6439
 
6440
   If you are willing to unflinchingly face the consequences of your own
6441
commands, you can disable this "feature":
6442
 
6443
`set confirm off'
6444
     Disables confirmation requests.
6445
 
6446
`set confirm on'
6447
     Enables confirmation requests (the default).
6448
 
6449
`show confirm'
6450
     Displays state of confirmation requests.
6451
 
6452
 
6453
   If you need to debug user-defined commands or sourced files you may
6454
find it useful to enable "command tracing".  In this mode each command
6455
will be printed as it is executed, prefixed with one or more `+'
6456
symbols, the quantity denoting the call depth of each command.
6457
 
6458
`set trace-commands on'
6459
     Enable command tracing.
6460
 
6461
`set trace-commands off'
6462
     Disable command tracing.
6463
 
6464
`show trace-commands'
6465
     Display the current state of command tracing.
6466
 
6467

6468
File: gdb.info,  Node: Debugging Output,  Prev: Messages/Warnings,  Up: Controlling GDB
6469
 
6470
19.8 Optional Messages about Internal Happenings
6471
================================================
6472
 
6473
GDB has commands that enable optional debugging messages from various
6474
GDB subsystems; normally these commands are of interest to GDB
6475
maintainers, or when reporting a bug.  This section documents those
6476
commands.
6477
 
6478
`set exec-done-display'
6479
     Turns on or off the notification of asynchronous commands'
6480
     completion.  When on, GDB will print a message when an
6481
     asynchronous command finishes its execution.  The default is off.
6482
 
6483
`show exec-done-display'
6484
     Displays the current setting of asynchronous command completion
6485
     notification.
6486
 
6487
`set debug arch'
6488
     Turns on or off display of gdbarch debugging info.  The default is
6489
     off
6490
 
6491
`show debug arch'
6492
     Displays the current state of displaying gdbarch debugging info.
6493
 
6494
`set debug aix-thread'
6495
     Display debugging messages about inner workings of the AIX thread
6496
     module.
6497
 
6498
`show debug aix-thread'
6499
     Show the current state of AIX thread debugging info display.
6500
 
6501
`set debug event'
6502
     Turns on or off display of GDB event debugging info.  The default
6503
     is off.
6504
 
6505
`show debug event'
6506
     Displays the current state of displaying GDB event debugging info.
6507
 
6508
`set debug expression'
6509
     Turns on or off display of debugging info about GDB expression
6510
     parsing.  The default is off.
6511
 
6512
`show debug expression'
6513
     Displays the current state of displaying debugging info about GDB
6514
     expression parsing.
6515
 
6516
`set debug frame'
6517
     Turns on or off display of GDB frame debugging info.  The default
6518
     is off.
6519
 
6520
`show debug frame'
6521
     Displays the current state of displaying GDB frame debugging info.
6522
 
6523
`set debug infrun'
6524
     Turns on or off display of GDB debugging info for running the
6525
     inferior.  The default is off.  `infrun.c' contains GDB's runtime
6526
     state machine used for implementing operations such as
6527
     single-stepping the inferior.
6528
 
6529
`show debug infrun'
6530
     Displays the current state of GDB inferior debugging.
6531
 
6532
`set debug lin-lwp'
6533
     Turns on or off debugging messages from the Linux LWP debug
6534
     support.
6535
 
6536
`show debug lin-lwp'
6537
     Show the current state of Linux LWP debugging messages.
6538
 
6539
`set debug observer'
6540
     Turns on or off display of GDB observer debugging.  This includes
6541
     info such as the notification of observable events.
6542
 
6543
`show debug observer'
6544
     Displays the current state of observer debugging.
6545
 
6546
`set debug overload'
6547
     Turns on or off display of GDB C++ overload debugging info. This
6548
     includes info such as ranking of functions, etc.  The default is
6549
     off.
6550
 
6551
`show debug overload'
6552
     Displays the current state of displaying GDB C++ overload
6553
     debugging info.
6554
 
6555
`set debug remote'
6556
     Turns on or off display of reports on all packets sent back and
6557
     forth across the serial line to the remote machine.  The info is
6558
     printed on the GDB standard output stream. The default is off.
6559
 
6560
`show debug remote'
6561
     Displays the state of display of remote packets.
6562
 
6563
`set debug serial'
6564
     Turns on or off display of GDB serial debugging info. The default
6565
     is off.
6566
 
6567
`show debug serial'
6568
     Displays the current state of displaying GDB serial debugging info.
6569
 
6570
`set debug solib-frv'
6571
     Turns on or off debugging messages for FR-V shared-library code.
6572
 
6573
`show debug solib-frv'
6574
     Display the current state of FR-V shared-library code debugging
6575
     messages.
6576
 
6577
`set debug target'
6578
     Turns on or off display of GDB target debugging info. This info
6579
     includes what is going on at the target level of GDB, as it
6580
     happens. The default is 0.  Set it to 1 to track events, and to 2
6581
     to also track the value of large memory transfers.  Changes to
6582
     this flag do not take effect until the next time you connect to a
6583
     target or use the `run' command.
6584
 
6585
`show debug target'
6586
     Displays the current state of displaying GDB target debugging info.
6587
 
6588
`set debugvarobj'
6589
     Turns on or off display of GDB variable object debugging info. The
6590
     default is off.
6591
 
6592
`show debugvarobj'
6593
     Displays the current state of displaying GDB variable object
6594
     debugging info.
6595
 
6596
`set debug xml'
6597
     Turns on or off debugging messages for built-in XML parsers.
6598
 
6599
`show debug xml'
6600
     Displays the current state of XML debugging messages.
6601
 
6602

6603
File: gdb.info,  Node: Sequences,  Next: Interpreters,  Prev: Controlling GDB,  Up: Top
6604
 
6605
20 Canned Sequences of Commands
6606
*******************************
6607
 
6608
Aside from breakpoint commands (*note Breakpoint Command Lists: Break
6609
Commands.), GDB provides two ways to store sequences of commands for
6610
execution as a unit: user-defined commands and command files.
6611
 
6612
* Menu:
6613
 
6614
* Define::             How to define your own commands
6615
* Hooks::              Hooks for user-defined commands
6616
* Command Files::      How to write scripts of commands to be stored in a file
6617
* Output::             Commands for controlled output
6618
 
6619

6620
File: gdb.info,  Node: Define,  Next: Hooks,  Up: Sequences
6621
 
6622
20.1 User-defined Commands
6623
==========================
6624
 
6625
A "user-defined command" is a sequence of GDB commands to which you
6626
assign a new name as a command.  This is done with the `define'
6627
command.  User commands may accept up to 10 arguments separated by
6628
whitespace.  Arguments are accessed within the user command via
6629
`$arg0...$arg9'.  A trivial example:
6630
 
6631
     define adder
6632
       print $arg0 + $arg1 + $arg2
6633
     end
6634
 
6635
To execute the command use:
6636
 
6637
     adder 1 2 3
6638
 
6639
This defines the command `adder', which prints the sum of its three
6640
arguments.  Note the arguments are text substitutions, so they may
6641
reference variables, use complex expressions, or even perform inferior
6642
functions calls.
6643
 
6644
   In addition, `$argc' may be used to find out how many arguments have
6645
been passed.  This expands to a number in the range 0...10.
6646
 
6647
     define adder
6648
       if $argc == 2
6649
         print $arg0 + $arg1
6650
       end
6651
       if $argc == 3
6652
         print $arg0 + $arg1 + $arg2
6653
       end
6654
     end
6655
 
6656
`define COMMANDNAME'
6657
     Define a command named COMMANDNAME.  If there is already a command
6658
     by that name, you are asked to confirm that you want to redefine
6659
     it.
6660
 
6661
     The definition of the command is made up of other GDB command
6662
     lines, which are given following the `define' command.  The end of
6663
     these commands is marked by a line containing `end'.
6664
 
6665
`document COMMANDNAME'
6666
     Document the user-defined command COMMANDNAME, so that it can be
6667
     accessed by `help'.  The command COMMANDNAME must already be
6668
     defined.  This command reads lines of documentation just as
6669
     `define' reads the lines of the command definition, ending with
6670
     `end'.  After the `document' command is finished, `help' on command
6671
     COMMANDNAME displays the documentation you have written.
6672
 
6673
     You may use the `document' command again to change the
6674
     documentation of a command.  Redefining the command with `define'
6675
     does not change the documentation.
6676
 
6677
`dont-repeat'
6678
     Used inside a user-defined command, this tells GDB that this
6679
     command should not be repeated when the user hits  (*note
6680
     repeat last command: Command Syntax.).
6681
 
6682
`help user-defined'
6683
     List all user-defined commands, with the first line of the
6684
     documentation (if any) for each.
6685
 
6686
`show user'
6687
`show user COMMANDNAME'
6688
     Display the GDB commands used to define COMMANDNAME (but not its
6689
     documentation).  If no COMMANDNAME is given, display the
6690
     definitions for all user-defined commands.
6691
 
6692
`show max-user-call-depth'
6693
`set max-user-call-depth'
6694
     The value of `max-user-call-depth' controls how many recursion
6695
     levels are allowed in user-defined commands before GDB suspects an
6696
     infinite recursion and aborts the command.
6697
 
6698
   In addition to the above commands, user-defined commands frequently
6699
use control flow commands, described in *Note Command Files::.
6700
 
6701
   When user-defined commands are executed, the commands of the
6702
definition are not printed.  An error in any command stops execution of
6703
the user-defined command.
6704
 
6705
   If used interactively, commands that would ask for confirmation
6706
proceed without asking when used inside a user-defined command.  Many
6707
GDB commands that normally print messages to say what they are doing
6708
omit the messages when used in a user-defined command.
6709
 
6710

6711
File: gdb.info,  Node: Hooks,  Next: Command Files,  Prev: Define,  Up: Sequences
6712
 
6713
20.2 User-defined Command Hooks
6714
===============================
6715
 
6716
You may define "hooks", which are a special kind of user-defined
6717
command.  Whenever you run the command `foo', if the user-defined
6718
command `hook-foo' exists, it is executed (with no arguments) before
6719
that command.
6720
 
6721
   A hook may also be defined which is run after the command you
6722
executed.  Whenever you run the command `foo', if the user-defined
6723
command `hookpost-foo' exists, it is executed (with no arguments) after
6724
that command.  Post-execution hooks may exist simultaneously with
6725
pre-execution hooks, for the same command.
6726
 
6727
   It is valid for a hook to call the command which it hooks.  If this
6728
occurs, the hook is not re-executed, thereby avoiding infinite
6729
recursion.
6730
 
6731
   In addition, a pseudo-command, `stop' exists.  Defining
6732
(`hook-stop') makes the associated commands execute every time
6733
execution stops in your program: before breakpoint commands are run,
6734
displays are printed, or the stack frame is printed.
6735
 
6736
   For example, to ignore `SIGALRM' signals while single-stepping, but
6737
treat them normally during normal execution, you could define:
6738
 
6739
     define hook-stop
6740
     handle SIGALRM nopass
6741
     end
6742
 
6743
     define hook-run
6744
     handle SIGALRM pass
6745
     end
6746
 
6747
     define hook-continue
6748
     handle SIGALRM pass
6749
     end
6750
 
6751
   As a further example, to hook at the beginning and end of the `echo'
6752
command, and to add extra text to the beginning and end of the message,
6753
you could define:
6754
 
6755
     define hook-echo
6756
     echo <<<---
6757
     end
6758
 
6759
     define hookpost-echo
6760
     echo --->>>\n
6761
     end
6762
 
6763
     (gdb) echo Hello World
6764
     <<<---Hello World--->>>
6765
     (gdb)
6766
 
6767
   You can define a hook for any single-word command in GDB, but not
6768
for command aliases; you should define a hook for the basic command
6769
name, e.g.  `backtrace' rather than `bt'.  If an error occurs during
6770
the execution of your hook, execution of GDB commands stops and GDB
6771
issues a prompt (before the command that you actually typed had a
6772
chance to run).
6773
 
6774
   If you try to define a hook which does not match any known command,
6775
you get a warning from the `define' command.
6776
 
6777

6778
File: gdb.info,  Node: Command Files,  Next: Output,  Prev: Hooks,  Up: Sequences
6779
 
6780
20.3 Command Files
6781
==================
6782
 
6783
A command file for GDB is a text file made of lines that are GDB
6784
commands.  Comments (lines starting with `#') may also be included.  An
6785
empty line in a command file does nothing; it does not mean to repeat
6786
the last command, as it would from the terminal.
6787
 
6788
   You can request the execution of a command file with the `source'
6789
command:
6790
 
6791
`source [`-v'] FILENAME'
6792
     Execute the command file FILENAME.
6793
 
6794
   The lines in a command file are generally executed sequentially,
6795
unless the order of execution is changed by one of the _flow-control
6796
commands_ described below.  The commands are not printed as they are
6797
executed.  An error in any command terminates execution of the command
6798
file and control is returned to the console.
6799
 
6800
   GDB searches for FILENAME in the current directory and then on the
6801
search path (specified with the `directory' command).
6802
 
6803
   If `-v', for verbose mode, is given then GDB displays each command
6804
as it is executed.  The option must be given before FILENAME, and is
6805
interpreted as part of the filename anywhere else.
6806
 
6807
   Commands that would ask for confirmation if used interactively
6808
proceed without asking when used in a command file.  Many GDB commands
6809
that normally print messages to say what they are doing omit the
6810
messages when called from command files.
6811
 
6812
   GDB also accepts command input from standard input.  In this mode,
6813
normal output goes to standard output and error output goes to standard
6814
error.  Errors in a command file supplied on standard input do not
6815
terminate execution of the command file--execution continues with the
6816
next command.
6817
 
6818
     gdb < cmds > log 2>&1
6819
 
6820
   (The syntax above will vary depending on the shell used.) This
6821
example will execute commands from the file `cmds'. All output and
6822
errors would be directed to `log'.
6823
 
6824
   Since commands stored on command files tend to be more general than
6825
commands typed interactively, they frequently need to deal with
6826
complicated situations, such as different or unexpected values of
6827
variables and symbols, changes in how the program being debugged is
6828
built, etc.  GDB provides a set of flow-control commands to deal with
6829
these complexities.  Using these commands, you can write complex
6830
scripts that loop over data structures, execute commands conditionally,
6831
etc.
6832
 
6833
`if'
6834
`else'
6835
     This command allows to include in your script conditionally
6836
     executed commands. The `if' command takes a single argument, which
6837
     is an expression to evaluate.  It is followed by a series of
6838
     commands that are executed only if the expression is true (its
6839
     value is nonzero).  There can then optionally be an `else' line,
6840
     followed by a series of commands that are only executed if the
6841
     expression was false.  The end of the list is marked by a line
6842
     containing `end'.
6843
 
6844
`while'
6845
     This command allows to write loops.  Its syntax is similar to
6846
     `if': the command takes a single argument, which is an expression
6847
     to evaluate, and must be followed by the commands to execute, one
6848
     per line, terminated by an `end'.  These commands are called the
6849
     "body" of the loop.  The commands in the body of `while' are
6850
     executed repeatedly as long as the expression evaluates to true.
6851
 
6852
`loop_break'
6853
     This command exits the `while' loop in whose body it is included.
6854
     Execution of the script continues after that `while's `end' line.
6855
 
6856
`loop_continue'
6857
     This command skips the execution of the rest of the body of
6858
     commands in the `while' loop in whose body it is included.
6859
     Execution branches to the beginning of the `while' loop, where it
6860
     evaluates the controlling expression.
6861
 
6862
`end'
6863
     Terminate the block of commands that are the body of `if', `else',
6864
     or `while' flow-control commands.
6865
 
6866

6867
File: gdb.info,  Node: Output,  Prev: Command Files,  Up: Sequences
6868
 
6869
20.4 Commands for Controlled Output
6870
===================================
6871
 
6872
During the execution of a command file or a user-defined command, normal
6873
GDB output is suppressed; the only output that appears is what is
6874
explicitly printed by the commands in the definition.  This section
6875
describes three commands useful for generating exactly the output you
6876
want.
6877
 
6878
`echo TEXT'
6879
     Print TEXT.  Nonprinting characters can be included in TEXT using
6880
     C escape sequences, such as `\n' to print a newline.  *No newline
6881
     is printed unless you specify one.* In addition to the standard C
6882
     escape sequences, a backslash followed by a space stands for a
6883
     space.  This is useful for displaying a string with spaces at the
6884
     beginning or the end, since leading and trailing spaces are
6885
     otherwise trimmed from all arguments.  To print ` and foo = ', use
6886
     the command `echo \ and foo = \ '.
6887
 
6888
     A backslash at the end of TEXT can be used, as in C, to continue
6889
     the command onto subsequent lines.  For example,
6890
 
6891
          echo This is some text\n\
6892
          which is continued\n\
6893
          onto several lines.\n
6894
 
6895
     produces the same output as
6896
 
6897
          echo This is some text\n
6898
          echo which is continued\n
6899
          echo onto several lines.\n
6900
 
6901
`output EXPRESSION'
6902
     Print the value of EXPRESSION and nothing but that value: no
6903
     newlines, no `$NN = '.  The value is not entered in the value
6904
     history either.  *Note Expressions: Expressions, for more
6905
     information on expressions.
6906
 
6907
`output/FMT EXPRESSION'
6908
     Print the value of EXPRESSION in format FMT.  You can use the same
6909
     formats as for `print'.  *Note Output Formats: Output Formats, for
6910
     more information.
6911
 
6912
`printf TEMPLATE, EXPRESSIONS...'
6913
     Print the values of one or more EXPRESSIONS under the control of
6914
     the string TEMPLATE.  To print several values, make EXPRESSIONS be
6915
     a comma-separated list of individual expressions, which may be
6916
     either numbers or pointers.  Their values are printed as specified
6917
     by TEMPLATE, exactly as a C program would do by executing the code
6918
     below:
6919
 
6920
          printf (TEMPLATE, EXPRESSIONS...);
6921
 
6922
     As in `C' `printf', ordinary characters in TEMPLATE are printed
6923
     verbatim, while "conversion specification" introduced by the `%'
6924
     character cause subsequent EXPRESSIONS to be evaluated, their
6925
     values converted and formatted according to type and style
6926
     information encoded in the conversion specifications, and then
6927
     printed.
6928
 
6929
     For example, you can print two values in hex like this:
6930
 
6931
          printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
6932
 
6933
     `printf' supports all the standard `C' conversion specifications,
6934
     including the flags and modifiers between the `%' character and
6935
     the conversion letter, with the following exceptions:
6936
 
6937
        * The argument-ordering modifiers, such as `2$', are not
6938
          supported.
6939
 
6940
        * The modifier `*' is not supported for specifying precision or
6941
          width.
6942
 
6943
        * The `'' flag (for separation of digits into groups according
6944
          to `LC_NUMERIC'') is not supported.
6945
 
6946
        * The type modifiers `hh', `j', `t', and `z' are not supported.
6947
 
6948
        * The conversion letter `n' (as in `%n') is not supported.
6949
 
6950
        * The conversion letters `a' and `A' are not supported.
6951
 
6952
     Note that the `ll' type modifier is supported only if the
6953
     underlying `C' implementation used to build GDB supports the `long
6954
     long int' type, and the `L' type modifier is supported only if
6955
     `long double' type is available.
6956
 
6957
     As in `C', `printf' supports simple backslash-escape sequences,
6958
     such as `\n', `\t', `\\', `\"', `\a', and `\f', that consist of
6959
     backslash followed by a single character.  Octal and hexadecimal
6960
     escape sequences are not supported.
6961
 
6962
     Additionally, `printf' supports conversion specifications for DFP
6963
     ("Decimal Floating Point") types using the following length
6964
     modifiers together with a floating point specifier.  letters:
6965
 
6966
        * `H' for printing `Decimal32' types.
6967
 
6968
        * `D' for printing `Decimal64' types.
6969
 
6970
        * `DD' for printing `Decimal128' types.
6971
 
6972
     If the underlying `C' implementation used to build GDB has support
6973
     for the three length modifiers for DFP types, other modifiers such
6974
     as width and precision will also be available for GDB to use.
6975
 
6976
     In case there is no such `C' support, no additional modifiers will
6977
     be available and the value will be printed in the standard way.
6978
 
6979
     Here's an example of printing DFP types using the above conversion
6980
     letters:
6981
          printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
6982
 
6983
 
6984

6985
File: gdb.info,  Node: Interpreters,  Next: TUI,  Prev: Sequences,  Up: Top
6986
 
6987
21 Command Interpreters
6988
***********************
6989
 
6990
GDB supports multiple command interpreters, and some command
6991
infrastructure to allow users or user interface writers to switch
6992
between interpreters or run commands in other interpreters.
6993
 
6994
   GDB currently supports two command interpreters, the console
6995
interpreter (sometimes called the command-line interpreter or CLI) and
6996
the machine interface interpreter (or GDB/MI).  This manual describes
6997
both of these interfaces in great detail.
6998
 
6999
   By default, GDB will start with the console interpreter.  However,
7000
the user may choose to start GDB with another interpreter by specifying
7001
the `-i' or `--interpreter' startup options.  Defined interpreters
7002
include:
7003
 
7004
`console'
7005
     The traditional console or command-line interpreter.  This is the
7006
     most often used interpreter with GDB. With no interpreter
7007
     specified at runtime, GDB will use this interpreter.
7008
 
7009
`mi'
7010
     The newest GDB/MI interface (currently `mi2').  Used primarily by
7011
     programs wishing to use GDB as a backend for a debugger GUI or an
7012
     IDE.  For more information, see *Note The GDB/MI Interface: GDB/MI.
7013
 
7014
`mi2'
7015
     The current GDB/MI interface.
7016
 
7017
`mi1'
7018
     The GDB/MI interface included in GDB 5.1, 5.2, and 5.3.
7019
 
7020
 
7021
   The interpreter being used by GDB may not be dynamically switched at
7022
runtime.  Although possible, this could lead to a very precarious
7023
situation.  Consider an IDE using GDB/MI.  If a user enters the command
7024
"interpreter-set console" in a console view, GDB would switch to using
7025
the console interpreter, rendering the IDE inoperable!
7026
 
7027
   Although you may only choose a single interpreter at startup, you
7028
may execute commands in any interpreter from the current interpreter
7029
using the appropriate command.  If you are running the console
7030
interpreter, simply use the `interpreter-exec' command:
7031
 
7032
     interpreter-exec mi "-data-list-register-names"
7033
 
7034
   GDB/MI has a similar command, although it is only available in
7035
versions of GDB which support GDB/MI version 2 (or greater).
7036
 
7037

7038
File: gdb.info,  Node: TUI,  Next: Emacs,  Prev: Interpreters,  Up: Top
7039
 
7040
22 GDB Text User Interface
7041
**************************
7042
 
7043
* Menu:
7044
 
7045
* TUI Overview::                TUI overview
7046
* TUI Keys::                    TUI key bindings
7047
* TUI Single Key Mode::         TUI single key mode
7048
* TUI Commands::                TUI-specific commands
7049
* TUI Configuration::           TUI configuration variables
7050
 
7051
   The GDB Text User Interface (TUI) is a terminal interface which uses
7052
the `curses' library to show the source file, the assembly output, the
7053
program registers and GDB commands in separate text windows.  The TUI
7054
mode is supported only on platforms where a suitable version of the
7055
`curses' library is available.
7056
 
7057
   The TUI mode is enabled by default when you invoke GDB as either
7058
`gdbtui' or `gdb -tui'.  You can also switch in and out of TUI mode
7059
while GDB runs by using various TUI commands and key bindings, such as
7060
`C-x C-a'.  *Note TUI Key Bindings: TUI Keys.
7061
 
7062

7063
File: gdb.info,  Node: TUI Overview,  Next: TUI Keys,  Up: TUI
7064
 
7065
22.1 TUI Overview
7066
=================
7067
 
7068
In TUI mode, GDB can display several text windows:
7069
 
7070
_command_
7071
     This window is the GDB command window with the GDB prompt and the
7072
     GDB output.  The GDB input is still managed using readline.
7073
 
7074
_source_
7075
     The source window shows the source file of the program.  The
7076
     current line and active breakpoints are displayed in this window.
7077
 
7078
_assembly_
7079
     The assembly window shows the disassembly output of the program.
7080
 
7081
_register_
7082
     This window shows the processor registers.  Registers are
7083
     highlighted when their values change.
7084
 
7085
   The source and assembly windows show the current program position by
7086
highlighting the current line and marking it with a `>' marker.
7087
Breakpoints are indicated with two markers.  The first marker indicates
7088
the breakpoint type:
7089
 
7090
`B'
7091
     Breakpoint which was hit at least once.
7092
 
7093
`b'
7094
     Breakpoint which was never hit.
7095
 
7096
`H'
7097
     Hardware breakpoint which was hit at least once.
7098
 
7099
`h'
7100
     Hardware breakpoint which was never hit.
7101
 
7102
   The second marker indicates whether the breakpoint is enabled or not:
7103
 
7104
`+'
7105
     Breakpoint is enabled.
7106
 
7107
`-'
7108
     Breakpoint is disabled.
7109
 
7110
   The source, assembly and register windows are updated when the
7111
current thread changes, when the frame changes, or when the program
7112
counter changes.
7113
 
7114
   These windows are not all visible at the same time.  The command
7115
window is always visible.  The others can be arranged in several
7116
layouts:
7117
 
7118
   * source only,
7119
 
7120
   * assembly only,
7121
 
7122
   * source and assembly,
7123
 
7124
   * source and registers, or
7125
 
7126
   * assembly and registers.
7127
 
7128
   A status line above the command window shows the following
7129
information:
7130
 
7131
_target_
7132
     Indicates the current GDB target.  (*note Specifying a Debugging
7133
     Target: Targets.).
7134
 
7135
_process_
7136
     Gives the current process or thread number.  When no process is
7137
     being debugged, this field is set to `No process'.
7138
 
7139
_function_
7140
     Gives the current function name for the selected frame.  The name
7141
     is demangled if demangling is turned on (*note Print Settings::).
7142
     When there is no symbol corresponding to the current program
7143
     counter, the string `??' is displayed.
7144
 
7145
_line_
7146
     Indicates the current line number for the selected frame.  When
7147
     the current line number is not known, the string `??' is displayed.
7148
 
7149
_pc_
7150
     Indicates the current program counter address.
7151
 
7152

7153
File: gdb.info,  Node: TUI Keys,  Next: TUI Single Key Mode,  Prev: TUI Overview,  Up: TUI
7154
 
7155
22.2 TUI Key Bindings
7156
=====================
7157
 
7158
The TUI installs several key bindings in the readline keymaps (*note
7159
Command Line Editing::).  The following key bindings are installed for
7160
both TUI mode and the GDB standard mode.
7161
 
7162
`C-x C-a'
7163
`C-x a'
7164
`C-x A'
7165
     Enter or leave the TUI mode.  When leaving the TUI mode, the
7166
     curses window management stops and GDB operates using its standard
7167
     mode, writing on the terminal directly.  When reentering the TUI
7168
     mode, control is given back to the curses windows.  The screen is
7169
     then refreshed.
7170
 
7171
`C-x 1'
7172
     Use a TUI layout with only one window.  The layout will either be
7173
     `source' or `assembly'.  When the TUI mode is not active, it will
7174
     switch to the TUI mode.
7175
 
7176
     Think of this key binding as the Emacs `C-x 1' binding.
7177
 
7178
`C-x 2'
7179
     Use a TUI layout with at least two windows.  When the current
7180
     layout already has two windows, the next layout with two windows
7181
     is used.  When a new layout is chosen, one window will always be
7182
     common to the previous layout and the new one.
7183
 
7184
     Think of it as the Emacs `C-x 2' binding.
7185
 
7186
`C-x o'
7187
     Change the active window.  The TUI associates several key bindings
7188
     (like scrolling and arrow keys) with the active window.  This
7189
     command gives the focus to the next TUI window.
7190
 
7191
     Think of it as the Emacs `C-x o' binding.
7192
 
7193
`C-x s'
7194
     Switch in and out of the TUI SingleKey mode that binds single keys
7195
     to GDB commands (*note TUI Single Key Mode::).
7196
 
7197
   The following key bindings only work in the TUI mode:
7198
 
7199
7200
     Scroll the active window one page up.
7201
 
7202
7203
     Scroll the active window one page down.
7204
 
7205
7206
     Scroll the active window one line up.
7207
 
7208
7209
     Scroll the active window one line down.
7210
 
7211
7212
     Scroll the active window one column left.
7213
 
7214
7215
     Scroll the active window one column right.
7216
 
7217
`C-L'
7218
     Refresh the screen.
7219
 
7220
   Because the arrow keys scroll the active window in the TUI mode, they
7221
are not available for their normal use by readline unless the command
7222
window has the focus.  When another window is active, you must use
7223
other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to
7224
control the command window.
7225
 
7226

7227
File: gdb.info,  Node: TUI Single Key Mode,  Next: TUI Commands,  Prev: TUI Keys,  Up: TUI
7228
 
7229
22.3 TUI Single Key Mode
7230
========================
7231
 
7232
The TUI also provides a "SingleKey" mode, which binds several
7233
frequently used GDB commands to single keys.  Type `C-x s' to switch
7234
into this mode, where the following key bindings are used:
7235
 
7236
`c'
7237
     continue
7238
 
7239
`d'
7240
     down
7241
 
7242
`f'
7243
     finish
7244
 
7245
`n'
7246
     next
7247
 
7248
`q'
7249
     exit the SingleKey mode.
7250
 
7251
`r'
7252
     run
7253
 
7254
`s'
7255
     step
7256
 
7257
`u'
7258
     up
7259
 
7260
`v'
7261
     info locals
7262
 
7263
`w'
7264
     where
7265
 
7266
   Other keys temporarily switch to the GDB command prompt.  The key
7267
that was pressed is inserted in the editing buffer so that it is
7268
possible to type most GDB commands without interaction with the TUI
7269
SingleKey mode.  Once the command is entered the TUI SingleKey mode is
7270
restored.  The only way to permanently leave this mode is by typing `q'
7271
or `C-x s'.
7272
 
7273

7274
File: gdb.info,  Node: TUI Commands,  Next: TUI Configuration,  Prev: TUI Single Key Mode,  Up: TUI
7275
 
7276
22.4 TUI-specific Commands
7277
==========================
7278
 
7279
The TUI has specific commands to control the text windows.  These
7280
commands are always available, even when GDB is not in the TUI mode.
7281
When GDB is in the standard mode, most of these commands will
7282
automatically switch to the TUI mode.
7283
 
7284
`info win'
7285
     List and give the size of all displayed windows.
7286
 
7287
`layout next'
7288
     Display the next layout.
7289
 
7290
`layout prev'
7291
     Display the previous layout.
7292
 
7293
`layout src'
7294
     Display the source window only.
7295
 
7296
`layout asm'
7297
     Display the assembly window only.
7298
 
7299
`layout split'
7300
     Display the source and assembly window.
7301
 
7302
`layout regs'
7303
     Display the register window together with the source or assembly
7304
     window.
7305
 
7306
`focus next'
7307
     Make the next window active for scrolling.
7308
 
7309
`focus prev'
7310
     Make the previous window active for scrolling.
7311
 
7312
`focus src'
7313
     Make the source window active for scrolling.
7314
 
7315
`focus asm'
7316
     Make the assembly window active for scrolling.
7317
 
7318
`focus regs'
7319
     Make the register window active for scrolling.
7320
 
7321
`focus cmd'
7322
     Make the command window active for scrolling.
7323
 
7324
`refresh'
7325
     Refresh the screen.  This is similar to typing `C-L'.
7326
 
7327
`tui reg float'
7328
     Show the floating point registers in the register window.
7329
 
7330
`tui reg general'
7331
     Show the general registers in the register window.
7332
 
7333
`tui reg next'
7334
     Show the next register group.  The list of register groups as well
7335
     as their order is target specific.  The predefined register groups
7336
     are the following: `general', `float', `system', `vector', `all',
7337
     `save', `restore'.
7338
 
7339
`tui reg system'
7340
     Show the system registers in the register window.
7341
 
7342
`update'
7343
     Update the source window and the current execution point.
7344
 
7345
`winheight NAME +COUNT'
7346
`winheight NAME -COUNT'
7347
     Change the height of the window NAME by COUNT lines.  Positive
7348
     counts increase the height, while negative counts decrease it.
7349
 
7350
`tabset NCHARS'
7351
     Set the width of tab stops to be NCHARS characters.
7352
 
7353

7354
File: gdb.info,  Node: TUI Configuration,  Prev: TUI Commands,  Up: TUI
7355
 
7356
22.5 TUI Configuration Variables
7357
================================
7358
 
7359
Several configuration variables control the appearance of TUI windows.
7360
 
7361
`set tui border-kind KIND'
7362
     Select the border appearance for the source, assembly and register
7363
     windows.  The possible values are the following:
7364
    `space'
7365
          Use a space character to draw the border.
7366
 
7367
    `ascii'
7368
          Use ASCII characters `+', `-' and `|' to draw the border.
7369
 
7370
    `acs'
7371
          Use the Alternate Character Set to draw the border.  The
7372
          border is drawn using character line graphics if the terminal
7373
          supports them.
7374
 
7375
`set tui border-mode MODE'
7376
`set tui active-border-mode MODE'
7377
     Select the display attributes for the borders of the inactive
7378
     windows or the active window.  The MODE can be one of the
7379
     following:
7380
    `normal'
7381
          Use normal attributes to display the border.
7382
 
7383
    `standout'
7384
          Use standout mode.
7385
 
7386
    `reverse'
7387
          Use reverse video mode.
7388
 
7389
    `half'
7390
          Use half bright mode.
7391
 
7392
    `half-standout'
7393
          Use half bright and standout mode.
7394
 
7395
    `bold'
7396
          Use extra bright or bold mode.
7397
 
7398
    `bold-standout'
7399
          Use extra bright or bold and standout mode.
7400
 
7401

7402
File: gdb.info,  Node: Emacs,  Next: GDB/MI,  Prev: TUI,  Up: Top
7403
 
7404
23 Using GDB under GNU Emacs
7405
****************************
7406
 
7407
A special interface allows you to use GNU Emacs to view (and edit) the
7408
source files for the program you are debugging with GDB.
7409
 
7410
   To use this interface, use the command `M-x gdb' in Emacs.  Give the
7411
executable file you want to debug as an argument.  This command starts
7412
GDB as a subprocess of Emacs, with input and output through a newly
7413
created Emacs buffer.
7414
 
7415
   Running GDB under Emacs can be just like running GDB normally except
7416
for two things:
7417
 
7418
   * All "terminal" input and output goes through an Emacs buffer,
7419
     called the GUD buffer.
7420
 
7421
     This applies both to GDB commands and their output, and to the
7422
     input and output done by the program you are debugging.
7423
 
7424
     This is useful because it means that you can copy the text of
7425
     previous commands and input them again; you can even use parts of
7426
     the output in this way.
7427
 
7428
     All the facilities of Emacs' Shell mode are available for
7429
     interacting with your program.  In particular, you can send
7430
     signals the usual way--for example, `C-c C-c' for an interrupt,
7431
     `C-c C-z' for a stop.
7432
 
7433
   * GDB displays source code through Emacs.
7434
 
7435
     Each time GDB displays a stack frame, Emacs automatically finds the
7436
     source file for that frame and puts an arrow (`=>') at the left
7437
     margin of the current line.  Emacs uses a separate buffer for
7438
     source display, and splits the screen to show both your GDB session
7439
     and the source.
7440
 
7441
     Explicit GDB `list' or search commands still produce output as
7442
     usual, but you probably have no reason to use them from Emacs.
7443
 
7444
   We call this "text command mode".  Emacs 22.1, and later, also uses
7445
a graphical mode, enabled by default, which provides further buffers
7446
that can control the execution and describe the state of your program.
7447
*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface.
7448
 
7449
   If you specify an absolute file name when prompted for the `M-x gdb'
7450
argument, then Emacs sets your current working directory to where your
7451
program resides.  If you only specify the file name, then Emacs sets
7452
your current working directory to to the directory associated with the
7453
previous buffer.  In this case, GDB may find your program by searching
7454
your environment's `PATH' variable, but on some operating systems it
7455
might not find the source.  So, although the GDB input and output
7456
session proceeds normally, the auxiliary buffer does not display the
7457
current source and line of execution.
7458
 
7459
   The initial working directory of GDB is printed on the top line of
7460
the GUD buffer and this serves as a default for the commands that
7461
specify files for GDB to operate on.  *Note Commands to Specify Files:
7462
Files.
7463
 
7464
   By default, `M-x gdb' calls the program called `gdb'.  If you need
7465
to call GDB by a different name (for example, if you keep several
7466
configurations around, with different names) you can customize the
7467
Emacs variable `gud-gdb-command-name' to run the one you want.
7468
 
7469
   In the GUD buffer, you can use these special Emacs commands in
7470
addition to the standard Shell mode commands:
7471
 
7472
`C-h m'
7473
     Describe the features of Emacs' GUD Mode.
7474
 
7475
`C-c C-s'
7476
     Execute to another source line, like the GDB `step' command; also
7477
     update the display window to show the current file and location.
7478
 
7479
`C-c C-n'
7480
     Execute to next source line in this function, skipping all function
7481
     calls, like the GDB `next' command.  Then update the display window
7482
     to show the current file and location.
7483
 
7484
`C-c C-i'
7485
     Execute one instruction, like the GDB `stepi' command; update
7486
     display window accordingly.
7487
 
7488
`C-c C-f'
7489
     Execute until exit from the selected stack frame, like the GDB
7490
     `finish' command.
7491
 
7492
`C-c C-r'
7493
     Continue execution of your program, like the GDB `continue'
7494
     command.
7495
 
7496
`C-c <'
7497
     Go up the number of frames indicated by the numeric argument
7498
     (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up'
7499
     command.
7500
 
7501
`C-c >'
7502
     Go down the number of frames indicated by the numeric argument,
7503
     like the GDB `down' command.
7504
 
7505
   In any source file, the Emacs command `C-x ' (`gud-break')
7506
tells GDB to set a breakpoint on the source line point is on.
7507
 
7508
   In text command mode, if you type `M-x speedbar', Emacs displays a
7509
separate frame which shows a backtrace when the GUD buffer is current.
7510
Move point to any frame in the stack and type  to make it become
7511
the current frame and display the associated source in the source
7512
buffer.  Alternatively, click `Mouse-2' to make the selected frame
7513
become the current one.  In graphical mode, the speedbar displays watch
7514
expressions.
7515
 
7516
   If you accidentally delete the source-display buffer, an easy way to
7517
get it back is to type the command `f' in the GDB buffer, to request a
7518
frame display; when you run under Emacs, this recreates the source
7519
buffer if necessary to show you the context of the current frame.
7520
 
7521
   The source files displayed in Emacs are in ordinary Emacs buffers
7522
which are visiting the source files in the usual way.  You can edit the
7523
files with these buffers if you wish; but keep in mind that GDB
7524
communicates with Emacs in terms of line numbers.  If you add or delete
7525
lines from the text, the line numbers that GDB knows cease to
7526
correspond properly with the code.
7527
 
7528
   A more detailed description of Emacs' interaction with GDB is given
7529
in the Emacs manual (*note Debuggers: (Emacs)Debuggers.).
7530
 
7531

7532
File: gdb.info,  Node: GDB/MI,  Next: Annotations,  Prev: Emacs,  Up: Top
7533
 
7534
24 The GDB/MI Interface
7535
***********************
7536
 
7537
Function and Purpose
7538
====================
7539
 
7540
GDB/MI is a line based machine oriented text interface to GDB and is
7541
activated by specifying using the `--interpreter' command line option
7542
(*note Mode Options::).  It is specifically intended to support the
7543
development of systems which use the debugger as just one small
7544
component of a larger system.
7545
 
7546
   This chapter is a specification of the GDB/MI interface.  It is
7547
written in the form of a reference manual.
7548
 
7549
   Note that GDB/MI is still under construction, so some of the
7550
features described below are incomplete and subject to change (*note
7551
GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.).
7552
 
7553
Notation and Terminology
7554
========================
7555
 
7556
This chapter uses the following notation:
7557
 
7558
   * `|' separates two alternatives.
7559
 
7560
   * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or
7561
     may not be given.
7562
 
7563
   * `( GROUP )*' means that GROUP inside the parentheses may repeat
7564
     zero or more times.
7565
 
7566
   * `( GROUP )+' means that GROUP inside the parentheses may repeat
7567
     one or more times.
7568
 
7569
   * `"STRING"' means a literal STRING.
7570
 
7571
* Menu:
7572
 
7573
* GDB/MI Command Syntax::
7574
* GDB/MI Compatibility with CLI::
7575
* GDB/MI Development and Front Ends::
7576
* GDB/MI Output Records::
7577
* GDB/MI Simple Examples::
7578
* GDB/MI Command Description Format::
7579
* GDB/MI Breakpoint Commands::
7580
* GDB/MI Program Context::
7581
* GDB/MI Thread Commands::
7582
* GDB/MI Program Execution::
7583
* GDB/MI Stack Manipulation::
7584
* GDB/MI Variable Objects::
7585
* GDB/MI Data Manipulation::
7586
* GDB/MI Tracepoint Commands::
7587
* GDB/MI Symbol Query::
7588
* GDB/MI File Commands::
7589
* GDB/MI Target Manipulation::
7590
* GDB/MI File Transfer Commands::
7591
* GDB/MI Miscellaneous Commands::
7592
 
7593

7594
File: gdb.info,  Node: GDB/MI Command Syntax,  Next: GDB/MI Compatibility with CLI,  Up: GDB/MI
7595
 
7596
24.1 GDB/MI Command Syntax
7597
==========================
7598
 
7599
* Menu:
7600
 
7601
* GDB/MI Input Syntax::
7602
* GDB/MI Output Syntax::
7603
 
7604

7605
File: gdb.info,  Node: GDB/MI Input Syntax,  Next: GDB/MI Output Syntax,  Up: GDB/MI Command Syntax
7606
 
7607
24.1.1 GDB/MI Input Syntax
7608
--------------------------
7609
 
7610
`COMMAND ==>'
7611
     `CLI-COMMAND | MI-COMMAND'
7612
 
7613
`CLI-COMMAND ==>'
7614
     `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB
7615
     CLI command.
7616
 
7617
`MI-COMMAND ==>'
7618
     `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " "
7619
     PARAMETER )* NL'
7620
 
7621
`TOKEN ==>'
7622
     "any sequence of digits"
7623
 
7624
`OPTION ==>'
7625
     `"-" PARAMETER [ " " PARAMETER ]'
7626
 
7627
`PARAMETER ==>'
7628
     `NON-BLANK-SEQUENCE | C-STRING'
7629
 
7630
`OPERATION ==>'
7631
     _any of the operations described in this chapter_
7632
 
7633
`NON-BLANK-SEQUENCE ==>'
7634
     _anything, provided it doesn't contain special characters such as
7635
     "-", NL, """ and of course " "_
7636
 
7637
`C-STRING ==>'
7638
     `""" SEVEN-BIT-ISO-C-STRING-CONTENT """'
7639
 
7640
`NL ==>'
7641
     `CR | CR-LF'
7642
 
7643
Notes:
7644
 
7645
   * The CLI commands are still handled by the MI interpreter; their
7646
     output is described below.
7647
 
7648
   * The `TOKEN', when present, is passed back when the command
7649
     finishes.
7650
 
7651
   * Some MI commands accept optional arguments as part of the parameter
7652
     list.  Each option is identified by a leading `-' (dash) and may be
7653
     followed by an optional argument parameter.  Options occur first
7654
     in the parameter list and can be delimited from normal parameters
7655
     using `--' (this is useful when some parameters begin with a dash).
7656
 
7657
   Pragmatics:
7658
 
7659
   * We want easy access to the existing CLI syntax (for debugging).
7660
 
7661
   * We want it to be easy to spot a MI operation.
7662
 
7663

7664
File: gdb.info,  Node: GDB/MI Output Syntax,  Prev: GDB/MI Input Syntax,  Up: GDB/MI Command Syntax
7665
 
7666
24.1.2 GDB/MI Output Syntax
7667
---------------------------
7668
 
7669
The output from GDB/MI consists of zero or more out-of-band records
7670
followed, optionally, by a single result record.  This result record is
7671
for the most recent command.  The sequence of output records is
7672
terminated by `(gdb)'.
7673
 
7674
   If an input command was prefixed with a `TOKEN' then the
7675
corresponding output for that command will also be prefixed by that same
7676
TOKEN.
7677
 
7678
`OUTPUT ==>'
7679
     `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL'
7680
 
7681
`RESULT-RECORD ==>'
7682
     ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL'
7683
 
7684
`OUT-OF-BAND-RECORD ==>'
7685
     `ASYNC-RECORD | STREAM-RECORD'
7686
 
7687
`ASYNC-RECORD ==>'
7688
     `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT'
7689
 
7690
`EXEC-ASYNC-OUTPUT ==>'
7691
     `[ TOKEN ] "*" ASYNC-OUTPUT'
7692
 
7693
`STATUS-ASYNC-OUTPUT ==>'
7694
     `[ TOKEN ] "+" ASYNC-OUTPUT'
7695
 
7696
`NOTIFY-ASYNC-OUTPUT ==>'
7697
     `[ TOKEN ] "=" ASYNC-OUTPUT'
7698
 
7699
`ASYNC-OUTPUT ==>'
7700
     `ASYNC-CLASS ( "," RESULT )* NL'
7701
 
7702
`RESULT-CLASS ==>'
7703
     `"done" | "running" | "connected" | "error" | "exit"'
7704
 
7705
`ASYNC-CLASS ==>'
7706
     `"stopped" | OTHERS' (where OTHERS will be added depending on the
7707
     needs--this is still in development).
7708
 
7709
`RESULT ==>'
7710
     ` VARIABLE "=" VALUE'
7711
 
7712
`VARIABLE ==>'
7713
     ` STRING '
7714
 
7715
`VALUE ==>'
7716
     ` CONST | TUPLE | LIST '
7717
 
7718
`CONST ==>'
7719
     `C-STRING'
7720
 
7721
`TUPLE ==>'
7722
     ` "{}" | "{" RESULT ( "," RESULT )* "}" '
7723
 
7724
`LIST ==>'
7725
     ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )*
7726
     "]" '
7727
 
7728
`STREAM-RECORD ==>'
7729
     `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT'
7730
 
7731
`CONSOLE-STREAM-OUTPUT ==>'
7732
     `"~" C-STRING'
7733
 
7734
`TARGET-STREAM-OUTPUT ==>'
7735
     `"@" C-STRING'
7736
 
7737
`LOG-STREAM-OUTPUT ==>'
7738
     `"&" C-STRING'
7739
 
7740
`NL ==>'
7741
     `CR | CR-LF'
7742
 
7743
`TOKEN ==>'
7744
     _any sequence of digits_.
7745
 
7746
Notes:
7747
 
7748
   * All output sequences end in a single line containing a period.
7749
 
7750
   * The `TOKEN' is from the corresponding request.  If an execution
7751
     command is interrupted by the `-exec-interrupt' command, the TOKEN
7752
     associated with the `*stopped' message is the one of the original
7753
     execution command, not the one of the interrupt command.
7754
 
7755
   * STATUS-ASYNC-OUTPUT contains on-going status information about the
7756
     progress of a slow operation.  It can be discarded.  All status
7757
     output is prefixed by `+'.
7758
 
7759
   * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
7760
     (stopped, started, disappeared).  All async output is prefixed by
7761
     `*'.
7762
 
7763
   * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
7764
     client should handle (e.g., a new breakpoint information).  All
7765
     notify output is prefixed by `='.
7766
 
7767
   * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in
7768
     the console.  It is the textual response to a CLI command.  All
7769
     the console output is prefixed by `~'.
7770
 
7771
   * TARGET-STREAM-OUTPUT is the output produced by the target program.
7772
     All the target output is prefixed by `@'.
7773
 
7774
   * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
7775
     instance messages that should be displayed as part of an error
7776
     log.  All the log output is prefixed by `&'.
7777
 
7778
   * New GDB/MI commands should only output LISTS containing VALUES.
7779
 
7780
 
7781
   *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details
7782
about the various output records.
7783
 
7784

7785
File: gdb.info,  Node: GDB/MI Compatibility with CLI,  Next: GDB/MI Development and Front Ends,  Prev: GDB/MI Command Syntax,  Up: GDB/MI
7786
 
7787
24.2 GDB/MI Compatibility with CLI
7788
==================================
7789
 
7790
For the developers convenience CLI commands can be entered directly,
7791
but there may be some unexpected behaviour.  For example, commands that
7792
query the user will behave as if the user replied yes, breakpoint
7793
command lists are not executed and some CLI commands, such as `if',
7794
`when' and `define', prompt for further input with `>', which is not
7795
valid MI output.
7796
 
7797
   This feature may be removed at some stage in the future and it is
7798
recommended that front ends use the `-interpreter-exec' command (*note
7799
-interpreter-exec::).
7800
 
7801

7802
File: gdb.info,  Node: GDB/MI Development and Front Ends,  Next: GDB/MI Output Records,  Prev: GDB/MI Compatibility with CLI,  Up: GDB/MI
7803
 
7804
24.3 GDB/MI Development and Front Ends
7805
======================================
7806
 
7807
The application which takes the MI output and presents the state of the
7808
program being debugged to the user is called a "front end".
7809
 
7810
   Although GDB/MI is still incomplete, it is currently being used by a
7811
variety of front ends to GDB.  This makes it difficult to introduce new
7812
functionality without breaking existing usage.  This section tries to
7813
minimize the problems by describing how the protocol might change.
7814
 
7815
   Some changes in MI need not break a carefully designed front end, and
7816
for these the MI version will remain unchanged.  The following is a
7817
list of changes that may occur within one level, so front ends should
7818
parse MI output in a way that can handle them:
7819
 
7820
   * New MI commands may be added.
7821
 
7822
   * New fields may be added to the output of any MI command.
7823
 
7824
   * The range of values for fields with specified values, e.g.,
7825
     `in_scope' (*note -var-update::) may be extended.
7826
 
7827
 
7828
   If the changes are likely to break front ends, the MI version level
7829
will be increased by one.  This will allow the front end to parse the
7830
output according to the MI version.  Apart from mi0, new versions of
7831
GDB will not support old versions of MI and it will be the
7832
responsibility of the front end to work with the new one.
7833
 
7834
   The best way to avoid unexpected changes in MI that might break your
7835
front end is to make your project known to GDB developers and follow
7836
development on  and .
7837
There is also the mailing list ,
7838
hosted by the Free Standards Group, which has the aim of creating a
7839
more general MI protocol called Debugger Machine Interface (DMI) that
7840
will become a standard for all debuggers, not just GDB.
7841
 
7842

7843
File: gdb.info,  Node: GDB/MI Output Records,  Next: GDB/MI Simple Examples,  Prev: GDB/MI Development and Front Ends,  Up: GDB/MI
7844
 
7845
24.4 GDB/MI Output Records
7846
==========================
7847
 
7848
* Menu:
7849
 
7850
* GDB/MI Result Records::
7851
* GDB/MI Stream Records::
7852
* GDB/MI Out-of-band Records::
7853
 
7854

7855
File: gdb.info,  Node: GDB/MI Result Records,  Next: GDB/MI Stream Records,  Up: GDB/MI Output Records
7856
 
7857
24.4.1 GDB/MI Result Records
7858
----------------------------
7859
 
7860
In addition to a number of out-of-band notifications, the response to a
7861
GDB/MI command includes one of the following result indications:
7862
 
7863
`"^done" [ "," RESULTS ]'
7864
     The synchronous operation was successful, `RESULTS' are the return
7865
     values.
7866
 
7867
`"^running"'
7868
     The asynchronous operation was successfully started.  The target is
7869
     running.
7870
 
7871
`"^connected"'
7872
     GDB has connected to a remote target.
7873
 
7874
`"^error" "," C-STRING'
7875
     The operation failed.  The `C-STRING' contains the corresponding
7876
     error message.
7877
 
7878
`"^exit"'
7879
     GDB has terminated.
7880
 
7881
 
7882

7883
File: gdb.info,  Node: GDB/MI Stream Records,  Next: GDB/MI Out-of-band Records,  Prev: GDB/MI Result Records,  Up: GDB/MI Output Records
7884
 
7885
24.4.2 GDB/MI Stream Records
7886
----------------------------
7887
 
7888
GDB internally maintains a number of output streams: the console, the
7889
target, and the log.  The output intended for each of these streams is
7890
funneled through the GDB/MI interface using "stream records".
7891
 
7892
   Each stream record begins with a unique "prefix character" which
7893
identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output
7894
Syntax.).  In addition to the prefix, each stream record contains a
7895
`STRING-OUTPUT'.  This is either raw text (with an implicit new line)
7896
or a quoted C string (which does not contain an implicit newline).
7897
 
7898
`"~" STRING-OUTPUT'
7899
     The console output stream contains text that should be displayed
7900
     in the CLI console window.  It contains the textual responses to
7901
     CLI commands.
7902
 
7903
`"@" STRING-OUTPUT'
7904
     The target output stream contains any textual output from the
7905
     running target.  This is only present when GDB's event loop is
7906
     truly asynchronous, which is currently only the case for remote
7907
     targets.
7908
 
7909
`"&" STRING-OUTPUT'
7910
     The log stream contains debugging messages being produced by GDB's
7911
     internals.
7912
 
7913

7914
File: gdb.info,  Node: GDB/MI Out-of-band Records,  Prev: GDB/MI Stream Records,  Up: GDB/MI Output Records
7915
 
7916
24.4.3 GDB/MI Out-of-band Records
7917
---------------------------------
7918
 
7919
"Out-of-band" records are used to notify the GDB/MI client of
7920
additional changes that have occurred.  Those changes can either be a
7921
consequence of GDB/MI (e.g., a breakpoint modified) or a result of
7922
target activity (e.g., target stopped).
7923
 
7924
   The following is a preliminary list of possible out-of-band records.
7925
In particular, the EXEC-ASYNC-OUTPUT records.
7926
 
7927
`*stopped,reason="REASON"'
7928
 
7929
   REASON can be one of the following:
7930
 
7931
`breakpoint-hit'
7932
     A breakpoint was reached.
7933
 
7934
`watchpoint-trigger'
7935
     A watchpoint was triggered.
7936
 
7937
`read-watchpoint-trigger'
7938
     A read watchpoint was triggered.
7939
 
7940
`access-watchpoint-trigger'
7941
     An access watchpoint was triggered.
7942
 
7943
`function-finished'
7944
     An -exec-finish or similar CLI command was accomplished.
7945
 
7946
`location-reached'
7947
     An -exec-until or similar CLI command was accomplished.
7948
 
7949
`watchpoint-scope'
7950
     A watchpoint has gone out of scope.
7951
 
7952
`end-stepping-range'
7953
     An -exec-next, -exec-next-instruction, -exec-step,
7954
     -exec-step-instruction or similar CLI command was accomplished.
7955
 
7956
`exited-signalled'
7957
     The inferior exited because of a signal.
7958
 
7959
`exited'
7960
     The inferior exited.
7961
 
7962
`exited-normally'
7963
     The inferior exited normally.
7964
 
7965
`signal-received'
7966
     A signal was received by the inferior.
7967
 
7968

7969
File: gdb.info,  Node: GDB/MI Simple Examples,  Next: GDB/MI Command Description Format,  Prev: GDB/MI Output Records,  Up: GDB/MI
7970
 
7971
24.5 Simple Examples of GDB/MI Interaction
7972
==========================================
7973
 
7974
This subsection presents several simple examples of interaction using
7975
the GDB/MI interface.  In these examples, `->' means that the following
7976
line is passed to GDB/MI as input, while `<-' means the output received
7977
from GDB/MI.
7978
 
7979
   Note the line breaks shown in the examples are here only for
7980
readability, they don't appear in the real output.
7981
 
7982
Setting a Breakpoint
7983
--------------------
7984
 
7985
Setting a breakpoint generates synchronous output which contains
7986
detailed information of the breakpoint.
7987
 
7988
     -> -break-insert main
7989
     <- ^done,bkpt={number="1",type="breakpoint",disp="keep",
7990
         enabled="y",addr="0x08048564",func="main",file="myprog.c",
7991
         fullname="/home/nickrob/myprog.c",line="68",times="0"}
7992
     <- (gdb)
7993
 
7994
Program Execution
7995
-----------------
7996
 
7997
Program execution generates asynchronous records and MI gives the
7998
reason that execution stopped.
7999
 
8000
     -> -exec-run
8001
     <- ^running
8002
     <- (gdb)
8003
     <- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0",
8004
        frame={addr="0x08048564",func="main",
8005
        args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}],
8006
        file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"}
8007
     <- (gdb)
8008
     -> -exec-continue
8009
     <- ^running
8010
     <- (gdb)
8011
     <- *stopped,reason="exited-normally"
8012
     <- (gdb)
8013
 
8014
Quitting GDB
8015
------------
8016
 
8017
Quitting GDB just prints the result class `^exit'.
8018
 
8019
     -> (gdb)
8020
     <- -gdb-exit
8021
     <- ^exit
8022
 
8023
A Bad Command
8024
-------------
8025
 
8026
Here's what happens if you pass a non-existent command:
8027
 
8028
     -> -rubbish
8029
     <- ^error,msg="Undefined MI command: rubbish"
8030
     <- (gdb)
8031
 

powered by: WebSVN 2.1.0

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