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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdb.info-4] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 362 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2 106 markom
 
3
INFO-DIR-SECTION Programming & development tools.
4
START-INFO-DIR-ENTRY
5
* Gdb: (gdb).                     The GNU debugger.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the GNU debugger GDB.
9
 
10
   This is the Eighth Edition, March 2000, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 5.0.
12
 
13
   Copyright (C) 1988-2000 Free Software Foundation, Inc.
14
 
15
   Permission is granted to make and distribute verbatim copies of this
16
manual provided the copyright notice and this permission notice are
17
preserved on all copies.
18
 
19
   Permission is granted to copy and distribute modified versions of
20
this manual under the conditions for verbatim copying, provided also
21
that the entire resulting derived work is distributed under the terms
22
of a permission notice identical to this one.
23
 
24
   Permission is granted to copy and distribute translations of this
25
manual into another language, under the above conditions for modified
26
versions.
27
 
28

29
File: gdb.info,  Node: Expressions,  Next: Variables,  Up: Data
30
 
31
Expressions
32
===========
33
 
34
   `print' and many other GDB commands accept an expression and compute
35
its value.  Any kind of constant, variable or operator defined by the
36
programming language you are using is valid in an expression in GDB.
37
This includes conditional expressions, function calls, casts and string
38
constants.  It unfortunately does not include symbols defined by
39
preprocessor `#define' commands.
40
 
41
   GDB supports array constants in expressions input by the user.  The
42
syntax is {ELEMENT, ELEMENT...}.  For example, you can use the command
43
`print {1, 2, 3}' to build up an array in memory that is `malloc'ed in
44
the target program.
45
 
46
   Because C is so widespread, most of the expressions shown in
47
examples in this manual are in C.  *Note Using GDB with Different
48
Languages: Languages, for information on how to use expressions in other
49
languages.
50
 
51
   In this section, we discuss operators that you can use in GDB
52
expressions regardless of your programming language.
53
 
54
   Casts are supported in all languages, not just in C, because it is so
55
useful to cast a number into a pointer in order to examine a structure
56
at that address in memory.
57
 
58
   GDB supports these operators, in addition to those common to
59
programming languages:
60
 
61
`@'
62
     `@' is a binary operator for treating parts of memory as arrays.
63
     *Note Artificial arrays: Arrays, for more information.
64
 
65
`::'
66
     `::' allows you to specify a variable in terms of the file or
67
     function where it is defined.  *Note Program variables: Variables.
68
 
69
`{TYPE} ADDR'
70
     Refers to an object of type TYPE stored at address ADDR in memory.
71
     ADDR may be any expression whose value is an integer or pointer
72
     (but parentheses are required around binary operators, just as in
73
     a cast).  This construct is allowed regardless of what kind of
74
     data is normally supposed to reside at ADDR.
75
 
76

77
File: gdb.info,  Node: Variables,  Next: Arrays,  Prev: Expressions,  Up: Data
78
 
79
Program variables
80
=================
81
 
82
   The most common kind of expression to use is the name of a variable
83
in your program.
84
 
85
   Variables in expressions are understood in the selected stack frame
86
(*note Selecting a frame: Selection.); they must be either:
87
 
88
   * global (or file-static)
89
 
90
or
91
 
92
   * visible according to the scope rules of the programming language
93
     from the point of execution in that frame
94
 
95
This means that in the function
96
 
97
     foo (a)
98
          int a;
99
     {
100
       bar (a);
101
       {
102
         int b = test ();
103
         bar (b);
104
       }
105
     }
106
 
107
you can examine and use the variable `a' whenever your program is
108
executing within the function `foo', but you can only use or examine
109
the variable `b' while your program is executing inside the block where
110
`b' is declared.
111
 
112
   There is an exception: you can refer to a variable or function whose
113
scope is a single source file even if the current execution point is not
114
in this file.  But it is possible to have more than one such variable or
115
function with the same name (in different source files).  If that
116
happens, referring to that name has unpredictable effects.  If you wish,
117
you can specify a static variable in a particular function or file,
118
using the colon-colon notation:
119
 
120
     FILE::VARIABLE
121
     FUNCTION::VARIABLE
122
 
123
Here FILE or FUNCTION is the name of the context for the static
124
VARIABLE.  In the case of file names, you can use quotes to make sure
125
GDB parses the file name as a single word--for example, to print a
126
global value of `x' defined in `f2.c':
127
 
128
     (gdb) p 'f2.c'::x
129
 
130
   This use of `::' is very rarely in conflict with the very similar
131
use of the same notation in C++.  GDB also supports use of the C++
132
scope resolution operator in GDB expressions.
133
 
134
     _Warning:_ Occasionally, a local variable may appear to have the
135
     wrong value at certain points in a function--just after entry to a
136
     new scope, and just before exit.
137
   You may see this problem when you are stepping by machine
138
instructions.  This is because, on most machines, it takes more than
139
one instruction to set up a stack frame (including local variable
140
definitions); if you are stepping by machine instructions, variables
141
may appear to have the wrong values until the stack frame is completely
142
built.  On exit, it usually also takes more than one machine
143
instruction to destroy a stack frame; after you begin stepping through
144
that group of instructions, local variable definitions may be gone.
145
 
146
   This may also happen when the compiler does significant
147
optimizations.  To be sure of always seeing accurate values, turn off
148
all optimization when compiling.
149
 
150
   Another possible effect of compiler optimizations is to optimize
151
unused variables out of existence, or assign variables to registers (as
152
opposed to memory addresses).  Depending on the support for such cases
153
offered by the debug info format used by the compiler, GDB might not be
154
able to display values for such local variables.  If that happens, GDB
155
will print a message like this:
156
 
157
     No symbol "foo" in current context.
158
 
159
   To solve such problems, either recompile without optimizations, or
160
use a different debug info format, if the compiler supports several such
161
formats.  For example, GCC, the GNU C/C++ compiler usually supports the
162
`-gstabs' option.  `-gstabs' produces debug info in a format that is
163
superior to formats such as COFF.  You may be able to use DWARF-2
164
(`-gdwarf-2'), which is also an effective form for debug info.  See
165
*Note Options for Debugging Your Program or GNU CC: (gcc.info)Debugging
166
Options, for more information.
167
 
168

169
File: gdb.info,  Node: Arrays,  Next: Output Formats,  Prev: Variables,  Up: Data
170
 
171
Artificial arrays
172
=================
173
 
174
   It is often useful to print out several successive objects of the
175
same type in memory; a section of an array, or an array of dynamically
176
determined size for which only a pointer exists in the program.
177
 
178
   You can do this by referring to a contiguous span of memory as an
179
"artificial array", using the binary operator `@'.  The left operand of
180
`@' should be the first element of the desired array and be an
181
individual object.  The right operand should be the desired length of
182
the array.  The result is an array value whose elements are all of the
183
type of the left argument.  The first element is actually the left
184
argument; the second element comes from bytes of memory immediately
185
following those that hold the first element, and so on.  Here is an
186
example.  If a program says
187
 
188
     int *array = (int *) malloc (len * sizeof (int));
189
 
190
you can print the contents of `array' with
191
 
192
     p *array@len
193
 
194
   The left operand of `@' must reside in memory.  Array values made
195
with `@' in this way behave just like other arrays in terms of
196
subscripting, and are coerced to pointers when used in expressions.
197
Artificial arrays most often appear in expressions via the value history
198
(*note Value history: Value History.), after printing one out.
199
 
200
   Another way to create an artificial array is to use a cast.  This
201
re-interprets a value as if it were an array.  The value need not be in
202
memory:
203
     (gdb) p/x (short[2])0x12345678
204
     $1 = {0x1234, 0x5678}
205
 
206
   As a convenience, if you leave the array length out (as in
207
`(TYPE[])VALUE') GDB calculates the size to fill the value (as
208
`sizeof(VALUE)/sizeof(TYPE)':
209
     (gdb) p/x (short[])0x12345678
210
     $2 = {0x1234, 0x5678}
211
 
212
   Sometimes the artificial array mechanism is not quite enough; in
213
moderately complex data structures, the elements of interest may not
214
actually be adjacent--for example, if you are interested in the values
215
of pointers in an array.  One useful work-around in this situation is
216
to use a convenience variable (*note Convenience variables: Convenience
217
Vars.) as a counter in an expression that prints the first interesting
218
value, and then repeat that expression via .  For instance,
219
suppose you have an array `dtab' of pointers to structures, and you are
220
interested in the values of a field `fv' in each structure.  Here is an
221
example of what you might type:
222
 
223
     set $i = 0
224
     p dtab[$i++]->fv
225
     
226
     
227
     ...
228
 
229

230
File: gdb.info,  Node: Output Formats,  Next: Memory,  Prev: Arrays,  Up: Data
231
 
232
Output formats
233
==============
234
 
235
   By default, GDB prints a value according to its data type.  Sometimes
236
this is not what you want.  For example, you might want to print a
237
number in hex, or a pointer in decimal.  Or you might want to view data
238
in memory at a certain address as a character string or as an
239
instruction.  To do these things, specify an "output format" when you
240
print a value.
241
 
242
   The simplest use of output formats is to say how to print a value
243
already computed.  This is done by starting the arguments of the
244
`print' command with a slash and a format letter.  The format letters
245
supported are:
246
 
247
`x'
248
     Regard the bits of the value as an integer, and print the integer
249
     in hexadecimal.
250
 
251
`d'
252
     Print as integer in signed decimal.
253
 
254
`u'
255
     Print as integer in unsigned decimal.
256
 
257
`o'
258
     Print as integer in octal.
259
 
260
`t'
261
     Print as integer in binary.  The letter `t' stands for "two".  (1)
262
 
263
`a'
264
     Print as an address, both absolute in hexadecimal and as an offset
265
     from the nearest preceding symbol.  You can use this format used
266
     to discover where (in what function) an unknown address is located:
267
 
268
          (gdb) p/a 0x54320
269
          $3 = 0x54320 <_initialize_vx+396>
270
 
271
`c'
272
     Regard as an integer and print it as a character constant.
273
 
274
`f'
275
     Regard the bits of the value as a floating point number and print
276
     using typical floating point syntax.
277
 
278
   For example, to print the program counter in hex (*note
279 362 markom
Registers::), type
280 106 markom
 
281
     p/x $pc
282
 
283
Note that no space is required before the slash; this is because command
284
names in GDB cannot contain a slash.
285
 
286
   To reprint the last value in the value history with a different
287
format, you can use the `print' command with just a format and no
288
expression.  For example, `p/x' reprints the last value in hex.
289
 
290
   ---------- Footnotes ----------
291
 
292
   (1) `b' cannot be used because these format letters are also used
293
with the `x' command, where `b' stands for "byte"; see *Note Examining
294
memory: Memory.
295
 
296

297
File: gdb.info,  Node: Memory,  Next: Auto Display,  Prev: Output Formats,  Up: Data
298
 
299
Examining memory
300
================
301
 
302
   You can use the command `x' (for "examine") to examine memory in any
303
of several formats, independently of your program's data types.
304
 
305
`x/NFU ADDR'
306
`x ADDR'
307
`x'
308
     Use the `x' command to examine memory.
309
 
310
   N, F, and U are all optional parameters that specify how much memory
311
to display and how to format it; ADDR is an expression giving the
312
address where you want to start displaying memory.  If you use defaults
313
for NFU, you need not type the slash `/'.  Several commands set
314
convenient defaults for ADDR.
315
 
316
N, the repeat count
317
     The repeat count is a decimal integer; the default is 1.  It
318
     specifies how much memory (counting by units U) to display.
319
 
320
F, the display format
321
     The display format is one of the formats used by `print', `s'
322
     (null-terminated string), or `i' (machine instruction).  The
323
     default is `x' (hexadecimal) initially.  The default changes each
324
     time you use either `x' or `print'.
325
 
326
U, the unit size
327
     The unit size is any of
328
 
329
    `b'
330
          Bytes.
331
 
332
    `h'
333
          Halfwords (two bytes).
334
 
335
    `w'
336
          Words (four bytes).  This is the initial default.
337
 
338
    `g'
339
          Giant words (eight bytes).
340
 
341
     Each time you specify a unit size with `x', that size becomes the
342
     default unit the next time you use `x'.  (For the `s' and `i'
343
     formats, the unit size is ignored and is normally not written.)
344
 
345
ADDR, starting display address
346
     ADDR is the address where you want GDB to begin displaying memory.
347
     The expression need not have a pointer value (though it may); it
348
     is always interpreted as an integer address of a byte of memory.
349
     *Note Expressions: Expressions, for more information on
350
     expressions.  The default for ADDR is usually just after the last
351
     address examined--but several other commands also set the default
352
     address: `info breakpoints' (to the address of the last breakpoint
353
     listed), `info line' (to the starting address of a line), and
354
     `print' (if you use it to display a value from memory).
355
 
356
   For example, `x/3uh 0x54320' is a request to display three halfwords
357
(`h') of memory, formatted as unsigned decimal integers (`u'), starting
358
at address `0x54320'.  `x/4xw $sp' prints the four words (`w') of
359
memory above the stack pointer (here, `$sp'; *note Registers:
360
Registers.) in hexadecimal (`x').
361
 
362
   Since the letters indicating unit sizes are all distinct from the
363
letters specifying output formats, you do not have to remember whether
364
unit size or format comes first; either order works.  The output
365
specifications `4xw' and `4wx' mean exactly the same thing.  (However,
366
the count N must come first; `wx4' does not work.)
367
 
368
   Even though the unit size U is ignored for the formats `s' and `i',
369
you might still want to use a count N; for example, `3i' specifies that
370
you want to see three machine instructions, including any operands.
371
The command `disassemble' gives an alternative way of inspecting
372
machine instructions; see *Note Source and machine code: Machine Code.
373
 
374
   All the defaults for the arguments to `x' are designed to make it
375
easy to continue scanning memory with minimal specifications each time
376
you use `x'.  For example, after you have inspected three machine
377
instructions with `x/3i ADDR', you can inspect the next seven with just
378
`x/7'.  If you use  to repeat the `x' command, the repeat count N
379
is used again; the other arguments default as for successive uses of
380
`x'.
381
 
382
   The addresses and contents printed by the `x' command are not saved
383
in the value history because there is often too much of them and they
384
would get in the way.  Instead, GDB makes these values available for
385
subsequent use in expressions as values of the convenience variables
386
`$_' and `$__'.  After an `x' command, the last address examined is
387
available for use in expressions in the convenience variable `$_'.  The
388
contents of that address, as examined, are available in the convenience
389
variable `$__'.
390
 
391
   If the `x' command has a repeat count, the address and contents saved
392
are from the last memory unit printed; this is not the same as the last
393
address printed if several units were printed on the last line of
394
output.
395
 
396

397
File: gdb.info,  Node: Auto Display,  Next: Print Settings,  Prev: Memory,  Up: Data
398
 
399
Automatic display
400
=================
401
 
402
   If you find that you want to print the value of an expression
403
frequently (to see how it changes), you might want to add it to the
404
"automatic display list" so that GDB prints its value each time your
405
program stops.  Each expression added to the list is given a number to
406
identify it; to remove an expression from the list, you specify that
407
number.  The automatic display looks like this:
408
 
409
     2: foo = 38
410
     3: bar[5] = (struct hack *) 0x3804
411
 
412
This display shows item numbers, expressions and their current values.
413
As with displays you request manually using `x' or `print', you can
414
specify the output format you prefer; in fact, `display' decides
415
whether to use `print' or `x' depending on how elaborate your format
416
specification is--it uses `x' if you specify a unit size, or one of the
417
two formats (`i' and `s') that are only supported by `x'; otherwise it
418
uses `print'.
419
 
420
`display EXPR'
421
     Add the expression EXPR to the list of expressions to display each
422
     time your program stops.  *Note Expressions: Expressions.
423
 
424
     `display' does not repeat if you press  again after using it.
425
 
426
`display/FMT EXPR'
427
     For FMT specifying only a display format and not a size or count,
428
     add the expression EXPR to the auto-display list but arrange to
429
     display it each time in the specified format FMT.  *Note Output
430
     formats: Output Formats.
431
 
432
`display/FMT ADDR'
433
     For FMT `i' or `s', or including a unit-size or a number of units,
434
     add the expression ADDR as a memory address to be examined each
435
     time your program stops.  Examining means in effect doing `x/FMT
436
     ADDR'.  *Note Examining memory: Memory.
437
 
438
   For example, `display/i $pc' can be helpful, to see the machine
439
instruction about to be executed each time execution stops (`$pc' is a
440
common name for the program counter; *note Registers: Registers.).
441
 
442
`undisplay DNUMS...'
443
`delete display DNUMS...'
444
     Remove item numbers DNUMS from the list of expressions to display.
445
 
446
     `undisplay' does not repeat if you press  after using it.
447
     (Otherwise you would just get the error `No display number ...'.)
448
 
449
`disable display DNUMS...'
450
     Disable the display of item numbers DNUMS.  A disabled display
451
     item is not printed automatically, but is not forgotten.  It may be
452
     enabled again later.
453
 
454
`enable display DNUMS...'
455
     Enable display of item numbers DNUMS.  It becomes effective once
456
     again in auto display of its expression, until you specify
457
     otherwise.
458
 
459
`display'
460
     Display the current values of the expressions on the list, just as
461
     is done when your program stops.
462
 
463
`info display'
464
     Print the list of expressions previously set up to display
465
     automatically, each one with its item number, but without showing
466
     the values.  This includes disabled expressions, which are marked
467
     as such.  It also includes expressions which would not be
468
     displayed right now because they refer to automatic variables not
469
     currently available.
470
 
471
   If a display expression refers to local variables, then it does not
472
make sense outside the lexical context for which it was set up.  Such an
473
expression is disabled when execution enters a context where one of its
474
variables is not defined.  For example, if you give the command
475
`display last_char' while inside a function with an argument
476
`last_char', GDB displays this argument while your program continues to
477
stop inside that function.  When it stops elsewhere--where there is no
478
variable `last_char'--the display is disabled automatically.  The next
479
time your program stops where `last_char' is meaningful, you can enable
480
the display expression once again.
481
 
482

483
File: gdb.info,  Node: Print Settings,  Next: Value History,  Prev: Auto Display,  Up: Data
484
 
485
Print settings
486
==============
487
 
488
   GDB provides the following ways to control how arrays, structures,
489
and symbols are printed.
490
 
491
These settings are useful for debugging programs in any language:
492
 
493
`set print address'
494
`set print address on'
495
     GDB prints memory addresses showing the location of stack traces,
496
     structure values, pointer values, breakpoints, and so forth, even
497
     when it also displays the contents of those addresses.  The default
498
     is `on'.  For example, this is what a stack frame display looks
499
     like with `set print address on':
500
 
501
          (gdb) f
502
          #0  set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>")
503
              at input.c:530
504
          530         if (lquote != def_lquote)
505
 
506
`set print address off'
507
     Do not print addresses when displaying their contents.  For
508
     example, this is the same stack frame displayed with `set print
509
     address off':
510
 
511
          (gdb) set print addr off
512
          (gdb) f
513
          #0  set_quotes (lq="<<", rq=">>") at input.c:530
514
          530         if (lquote != def_lquote)
515
 
516
     You can use `set print address off' to eliminate all machine
517
     dependent displays from the GDB interface.  For example, with
518
     `print address off', you should get the same text for backtraces on
519
     all machines--whether or not they involve pointer arguments.
520
 
521
`show print address'
522
     Show whether or not addresses are to be printed.
523
 
524
   When GDB prints a symbolic address, it normally prints the closest
525
earlier symbol plus an offset.  If that symbol does not uniquely
526
identify the address (for example, it is a name whose scope is a single
527
source file), you may need to clarify.  One way to do this is with
528
`info line', for example `info line *0x4537'.  Alternately, you can set
529
GDB to print the source file and line number when it prints a symbolic
530
address:
531
 
532
`set print symbol-filename on'
533
     Tell GDB to print the source file name and line number of a symbol
534
     in the symbolic form of an address.
535
 
536
`set print symbol-filename off'
537
     Do not print source file name and line number of a symbol.  This
538
     is the default.
539
 
540
`show print symbol-filename'
541
     Show whether or not GDB will print the source file name and line
542
     number of a symbol in the symbolic form of an address.
543
 
544
   Another situation where it is helpful to show symbol filenames and
545
line numbers is when disassembling code; GDB shows you the line number
546
and source file that corresponds to each instruction.
547
 
548
   Also, you may wish to see the symbolic form only if the address being
549
printed is reasonably close to the closest earlier symbol:
550
 
551
`set print max-symbolic-offset MAX-OFFSET'
552
     Tell GDB to only display the symbolic form of an address if the
553
     offset between the closest earlier symbol and the address is less
554
     than MAX-OFFSET.  The default is 0, which tells GDB to always
555
     print the symbolic form of an address if any symbol precedes it.
556
 
557
`show print max-symbolic-offset'
558
     Ask how large the maximum offset is that GDB prints in a symbolic
559
     address.
560
 
561
   If you have a pointer and you are not sure where it points, try `set
562
print symbol-filename on'.  Then you can determine the name and source
563
file location of the variable where it points, using `p/a POINTER'.
564
This interprets the address in symbolic form.  For example, here GDB
565
shows that a variable `ptt' points at another variable `t', defined in
566
`hi2.c':
567
 
568
     (gdb) set print symbol-filename on
569
     (gdb) p/a ptt
570
     $4 = 0xe008 
571
 
572
     _Warning:_ For pointers that point to a local variable, `p/a' does
573
     not show the symbol name and filename of the referent, even with
574
     the appropriate `set print' options turned on.
575
 
576
   Other settings control how different kinds of objects are printed:
577
 
578
`set print array'
579
`set print array on'
580
     Pretty print arrays.  This format is more convenient to read, but
581
     uses more space.  The default is off.
582
 
583
`set print array off'
584
     Return to compressed format for arrays.
585
 
586
`show print array'
587
     Show whether compressed or pretty format is selected for displaying
588
     arrays.
589
 
590
`set print elements NUMBER-OF-ELEMENTS'
591
     Set a limit on how many elements of an array GDB will print.  If
592
     GDB is printing a large array, it stops printing after it has
593
     printed the number of elements set by the `set print elements'
594
     command.  This limit also applies to the display of strings.  When
595
     GDB starts, this limit is set to 200.  Setting  NUMBER-OF-ELEMENTS
596
     to zero means that the printing is unlimited.
597
 
598
`show print elements'
599
     Display the number of elements of a large array that GDB will
600
     print.  If the number is 0, then the printing is unlimited.
601
 
602
`set print null-stop'
603
     Cause GDB to stop printing the characters of an array when the
604
     first NULL is encountered.  This is useful when large arrays
605
     actually contain only short strings.  The default is off.
606
 
607
`set print pretty on'
608
     Cause GDB to print structures in an indented format with one member
609
     per line, like this:
610
 
611
          $1 = {
612
            next = 0x0,
613
            flags = {
614
              sweet = 1,
615
              sour = 1
616
            },
617
            meat = 0x54 "Pork"
618
          }
619
 
620
`set print pretty off'
621
     Cause GDB to print structures in a compact format, like this:
622
 
623
          $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \
624
          meat = 0x54 "Pork"}
625
 
626
     This is the default format.
627
 
628
`show print pretty'
629
     Show which format GDB is using to print structures.
630
 
631
`set print sevenbit-strings on'
632
     Print using only seven-bit characters; if this option is set, GDB
633
     displays any eight-bit characters (in strings or character values)
634
     using the notation `\'NNN.  This setting is best if you are
635
     working in English (ASCII) and you use the high-order bit of
636
     characters as a marker or "meta" bit.
637
 
638
`set print sevenbit-strings off'
639
     Print full eight-bit characters.  This allows the use of more
640
     international character sets, and is the default.
641
 
642
`show print sevenbit-strings'
643
     Show whether or not GDB is printing only seven-bit characters.
644
 
645
`set print union on'
646
     Tell GDB to print unions which are contained in structures.  This
647
     is the default setting.
648
 
649
`set print union off'
650
     Tell GDB not to print unions which are contained in structures.
651
 
652
`show print union'
653
     Ask GDB whether or not it will print unions which are contained in
654
     structures.
655
 
656
     For example, given the declarations
657
 
658
          typedef enum {Tree, Bug} Species;
659
          typedef enum {Big_tree, Acorn, Seedling} Tree_forms;
660
          typedef enum {Caterpillar, Cocoon, Butterfly}
661
                        Bug_forms;
662
 
663
          struct thing {
664
            Species it;
665
            union {
666
              Tree_forms tree;
667
              Bug_forms bug;
668
            } form;
669
          };
670
 
671
          struct thing foo = {Tree, {Acorn}};
672
 
673
     with `set print union on' in effect `p foo' would print
674
 
675
          $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}}
676
 
677
     and with `set print union off' in effect it would print
678
 
679
          $1 = {it = Tree, form = {...}}
680
 
681
These settings are of interest when debugging C++ programs:
682
 
683
`set print demangle'
684
`set print demangle on'
685
     Print C++ names in their source form rather than in the encoded
686
     ("mangled") form passed to the assembler and linker for type-safe
687
     linkage.  The default is on.
688
 
689
`show print demangle'
690
     Show whether C++ names are printed in mangled or demangled form.
691
 
692
`set print asm-demangle'
693
`set print asm-demangle on'
694
     Print C++ names in their source form rather than their mangled
695
     form, even in assembler code printouts such as instruction
696
     disassemblies.  The default is off.
697
 
698
`show print asm-demangle'
699
     Show whether C++ names in assembly listings are printed in mangled
700
     or demangled form.
701
 
702
`set demangle-style STYLE'
703
     Choose among several encoding schemes used by different compilers
704
     to represent C++ names.  The choices for STYLE are currently:
705
 
706
    `auto'
707
          Allow GDB to choose a decoding style by inspecting your
708
          program.
709
 
710
    `gnu'
711
          Decode based on the GNU C++ compiler (`g++') encoding
712
          algorithm.  This is the default.
713
 
714
    `hp'
715
          Decode based on the HP ANSI C++ (`aCC') encoding algorithm.
716
 
717
    `lucid'
718
          Decode based on the Lucid C++ compiler (`lcc') encoding
719
          algorithm.
720
 
721
    `arm'
722
          Decode using the algorithm in the `C++ Annotated Reference
723
          Manual'.  *Warning:* this setting alone is not sufficient to
724
          allow debugging `cfront'-generated executables.  GDB would
725
          require further enhancement to permit that.
726
 
727
     If you omit STYLE, you will see a list of possible formats.
728
 
729
`show demangle-style'
730
     Display the encoding style currently in use for decoding C++
731
     symbols.
732
 
733
`set print object'
734
`set print object on'
735
     When displaying a pointer to an object, identify the _actual_
736
     (derived) type of the object rather than the _declared_ type, using
737
     the virtual function table.
738
 
739
`set print object off'
740
     Display only the declared type of objects, without reference to the
741
     virtual function table.  This is the default setting.
742
 
743
`show print object'
744
     Show whether actual, or declared, object types are displayed.
745
 
746
`set print static-members'
747
`set print static-members on'
748
     Print static members when displaying a C++ object.  The default is
749
     on.
750
 
751
`set print static-members off'
752
     Do not print static members when displaying a C++ object.
753
 
754
`show print static-members'
755
     Show whether C++ static members are printed, or not.
756
 
757
`set print vtbl'
758
`set print vtbl on'
759
     Pretty print C++ virtual function tables.  The default is off.
760
     (The `vtbl' commands do not work on programs compiled with the HP
761
     ANSI C++ compiler (`aCC').)
762
 
763
`set print vtbl off'
764
     Do not pretty print C++ virtual function tables.
765
 
766
`show print vtbl'
767
     Show whether C++ virtual function tables are pretty printed, or
768
     not.
769
 
770

771
File: gdb.info,  Node: Value History,  Next: Convenience Vars,  Prev: Print Settings,  Up: Data
772
 
773
Value history
774
=============
775
 
776
   Values printed by the `print' command are saved in the GDB "value
777
history".  This allows you to refer to them in other expressions.
778
Values are kept until the symbol table is re-read or discarded (for
779
example with the `file' or `symbol-file' commands).  When the symbol
780
table changes, the value history is discarded, since the values may
781
contain pointers back to the types defined in the symbol table.
782
 
783
   The values printed are given "history numbers" by which you can
784
refer to them.  These are successive integers starting with one.
785
`print' shows you the history number assigned to a value by printing
786
`$NUM = ' before the value; here NUM is the history number.
787
 
788
   To refer to any previous value, use `$' followed by the value's
789
history number.  The way `print' labels its output is designed to
790
remind you of this.  Just `$' refers to the most recent value in the
791
history, and `$$' refers to the value before that.  `$$N' refers to the
792
Nth value from the end; `$$2' is the value just prior to `$$', `$$1' is
793
equivalent to `$$', and `$$0' is equivalent to `$'.
794
 
795
   For example, suppose you have just printed a pointer to a structure
796
and want to see the contents of the structure.  It suffices to type
797
 
798
     p *$
799
 
800
   If you have a chain of structures where the component `next' points
801
to the next one, you can print the contents of the next one with this:
802
 
803
     p *$.next
804
 
805
You can print successive links in the chain by repeating this
806
command--which you can do by just typing .
807
 
808
   Note that the history records values, not expressions.  If the value
809
of `x' is 4 and you type these commands:
810
 
811
     print x
812
     set x=5
813
 
814
then the value recorded in the value history by the `print' command
815
remains 4 even though the value of `x' has changed.
816
 
817
`show values'
818
     Print the last ten values in the value history, with their item
819
     numbers.  This is like `p $$9' repeated ten times, except that
820
     `show values' does not change the history.
821
 
822
`show values N'
823
     Print ten history values centered on history item number N.
824
 
825
`show values +'
826
     Print ten history values just after the values last printed.  If
827
     no more values are available, `show values +' produces no display.
828
 
829
   Pressing  to repeat `show values N' has exactly the same effect
830
as `show values +'.
831
 
832

833
File: gdb.info,  Node: Convenience Vars,  Next: Registers,  Prev: Value History,  Up: Data
834
 
835
Convenience variables
836
=====================
837
 
838
   GDB provides "convenience variables" that you can use within GDB to
839
hold on to a value and refer to it later.  These variables exist
840
entirely within GDB; they are not part of your program, and setting a
841
convenience variable has no direct effect on further execution of your
842
program.  That is why you can use them freely.
843
 
844
   Convenience variables are prefixed with `$'.  Any name preceded by
845
`$' can be used for a convenience variable, unless it is one of the
846
predefined machine-specific register names (*note Registers:
847
Registers.).  (Value history references, in contrast, are _numbers_
848
preceded by `$'.  *Note Value history: Value History.)
849
 
850
   You can save a value in a convenience variable with an assignment
851
expression, just as you would set a variable in your program.  For
852
example:
853
 
854
     set $foo = *object_ptr
855
 
856
would save in `$foo' the value contained in the object pointed to by
857
`object_ptr'.
858
 
859
   Using a convenience variable for the first time creates it, but its
860
value is `void' until you assign a new value.  You can alter the value
861
with another assignment at any time.
862
 
863
   Convenience variables have no fixed types.  You can assign a
864
convenience variable any type of value, including structures and
865
arrays, even if that variable already has a value of a different type.
866
The convenience variable, when used as an expression, has the type of
867
its current value.
868
 
869
`show convenience'
870
     Print a list of convenience variables used so far, and their
871
     values.  Abbreviated `show conv'.
872
 
873
   One of the ways to use a convenience variable is as a counter to be
874
incremented or a pointer to be advanced.  For example, to print a field
875
from successive elements of an array of structures:
876
 
877
     set $i = 0
878
     print bar[$i++]->contents
879
 
880
Repeat that command by typing .
881
 
882
   Some convenience variables are created automatically by GDB and given
883
values likely to be useful.
884
 
885
`$_'
886
     The variable `$_' is automatically set by the `x' command to the
887
     last address examined (*note Examining memory: Memory.).  Other
888
     commands which provide a default address for `x' to examine also
889
     set `$_' to that address; these commands include `info line' and
890
     `info breakpoint'.  The type of `$_' is `void *' except when set
891
     by the `x' command, in which case it is a pointer to the type of
892
     `$__'.
893
 
894
`$__'
895
     The variable `$__' is automatically set by the `x' command to the
896
     value found in the last address examined.  Its type is chosen to
897
     match the format in which the data was printed.
898
 
899
`$_exitcode'
900
     The variable `$_exitcode' is automatically set to the exit code
901
     when the program being debugged terminates.
902
 
903
   On HP-UX systems, if you refer to a function or variable name that
904
begins with a dollar sign, GDB searches for a user or system name
905
first, before it searches for a convenience variable.
906
 
907

908
File: gdb.info,  Node: Registers,  Next: Floating Point Hardware,  Prev: Convenience Vars,  Up: Data
909
 
910
Registers
911
=========
912
 
913
   You can refer to machine register contents, in expressions, as
914
variables with names starting with `$'.  The names of registers are
915
different for each machine; use `info registers' to see the names used
916
on your machine.
917
 
918
`info registers'
919
     Print the names and values of all registers except floating-point
920
     registers (in the selected stack frame).
921
 
922
`info all-registers'
923
     Print the names and values of all registers, including
924
     floating-point registers.
925
 
926
`info registers REGNAME ...'
927
     Print the "relativized" value of each specified register REGNAME.
928
     As discussed in detail below, register values are normally
929
     relative to the selected stack frame.  REGNAME may be any register
930
     name valid on the machine you are using, with or without the
931
     initial `$'.
932
 
933
   GDB has four "standard" register names that are available (in
934
expressions) on most machines--whenever they do not conflict with an
935
architecture's canonical mnemonics for registers.  The register names
936
`$pc' and `$sp' are used for the program counter register and the stack
937
pointer.  `$fp' is used for a register that contains a pointer to the
938
current stack frame, and `$ps' is used for a register that contains the
939
processor status.  For example, you could print the program counter in
940
hex with
941
 
942
     p/x $pc
943
 
944
or print the instruction to be executed next with
945
 
946
     x/i $pc
947
 
948
or add four to the stack pointer(1) with
949
 
950
     set $sp += 4
951
 
952
   Whenever possible, these four standard register names are available
953
on your machine even though the machine has different canonical
954
mnemonics, so long as there is no conflict.  The `info registers'
955
command shows the canonical names.  For example, on the SPARC, `info
956
registers' displays the processor status register as `$psr' but you can
957
also refer to it as `$ps'; and on x86-based machines `$ps' is an alias
958
for the EFLAGS register.
959
 
960
   GDB always considers the contents of an ordinary register as an
961
integer when the register is examined in this way.  Some machines have
962
special registers which can hold nothing but floating point; these
963
registers are considered to have floating point values.  There is no way
964
to refer to the contents of an ordinary register as floating point value
965
(although you can _print_ it as a floating point value with `print/f
966
$REGNAME').
967
 
968
   Some registers have distinct "raw" and "virtual" data formats.  This
969
means that the data format in which the register contents are saved by
970
the operating system is not the same one that your program normally
971
sees.  For example, the registers of the 68881 floating point
972
coprocessor are always saved in "extended" (raw) format, but all C
973
programs expect to work with "double" (virtual) format.  In such cases,
974
GDB normally works with the virtual format only (the format that makes
975
sense for your program), but the `info registers' command prints the
976
data in both formats.
977
 
978
   Normally, register values are relative to the selected stack frame
979
(*note Selecting a frame: Selection.).  This means that you get the
980
value that the register would contain if all stack frames farther in
981
were exited and their saved registers restored.  In order to see the
982
true contents of hardware registers, you must select the innermost
983
frame (with `frame 0').
984
 
985
   However, GDB must deduce where registers are saved, from the machine
986
code generated by your compiler.  If some registers are not saved, or if
987
GDB is unable to locate the saved registers, the selected stack frame
988
makes no difference.
989
 
990
   ---------- Footnotes ----------
991
 
992
   (1) This is a way of removing one word from the stack, on machines
993
where stacks grow downward in memory (most machines, nowadays).  This
994
assumes that the innermost stack frame is selected; setting `$sp' is
995
not allowed when other stack frames are selected.  To pop entire frames
996
off the stack, regardless of machine architecture, use `return'; see
997
*Note Returning from a function: Returning.
998
 
999

1000
File: gdb.info,  Node: Floating Point Hardware,  Prev: Registers,  Up: Data
1001
 
1002
Floating point hardware
1003
=======================
1004
 
1005
   Depending on the configuration, GDB may be able to give you more
1006
information about the status of the floating point hardware.
1007
 
1008
`info float'
1009
     Display hardware-dependent information about the floating point
1010
     unit.  The exact contents and layout vary depending on the
1011
     floating point chip.  Currently, `info float' is supported on the
1012
     ARM and x86 machines.
1013
 
1014

1015
File: gdb.info,  Node: Languages,  Next: Symbols,  Prev: Data,  Up: Top
1016
 
1017
Using GDB with Different Languages
1018
**********************************
1019
 
1020
   Although programming languages generally have common aspects, they
1021
are rarely expressed in the same manner.  For instance, in ANSI C,
1022
dereferencing a pointer `p' is accomplished by `*p', but in Modula-2,
1023
it is accomplished by `p^'.  Values can also be represented (and
1024
displayed) differently.  Hex numbers in C appear as `0x1ae', while in
1025
Modula-2 they appear as `1AEH'.
1026
 
1027
   Language-specific information is built into GDB for some languages,
1028
allowing you to express operations like the above in your program's
1029
native language, and allowing GDB to output values in a manner
1030
consistent with the syntax of your program's native language.  The
1031
language you use to build expressions is called the "working language".
1032
 
1033
* Menu:
1034
 
1035
* Setting::                     Switching between source languages
1036
* Show::                        Displaying the language
1037
* Checks::                      Type and range checks
1038
* Support::                     Supported languages
1039
 
1040

1041
File: gdb.info,  Node: Setting,  Next: Show,  Up: Languages
1042
 
1043
Switching between source languages
1044
==================================
1045
 
1046
   There are two ways to control the working language--either have GDB
1047
set it automatically, or select it manually yourself.  You can use the
1048
`set language' command for either purpose.  On startup, GDB defaults to
1049
setting the language automatically.  The working language is used to
1050
determine how expressions you type are interpreted, how values are
1051
printed, etc.
1052
 
1053
   In addition to the working language, every source file that GDB
1054
knows about has its own working language.  For some object file
1055
formats, the compiler might indicate which language a particular source
1056
file is in.  However, most of the time GDB infers the language from the
1057
name of the file.  The language of a source file controls whether C++
1058
names are demangled--this way `backtrace' can show each frame
1059
appropriately for its own language.  There is no way to set the
1060
language of a source file from within GDB, but you can set the language
1061
associated with a filename extension.  *Note Displaying the language:
1062
Show.
1063
 
1064
   This is most commonly a problem when you use a program, such as
1065
`cfront' or `f2c', that generates C but is written in another language.
1066
In that case, make the program use `#line' directives in its C output;
1067
that way GDB will know the correct language of the source code of the
1068
original program, and will display that source code, not the generated
1069
C code.
1070
 
1071
* Menu:
1072
 
1073
* Filenames::                   Filename extensions and languages.
1074
* Manually::                    Setting the working language manually
1075
* Automatically::               Having GDB infer the source language
1076
 
1077

1078
File: gdb.info,  Node: Filenames,  Next: Manually,  Up: Setting
1079
 
1080
List of filename extensions and languages
1081
-----------------------------------------
1082
 
1083
   If a source file name ends in one of the following extensions, then
1084
GDB infers that its language is the one indicated.
1085
 
1086
`.c'
1087
     C source file
1088
 
1089
`.C'
1090
`.cc'
1091
`.cp'
1092
`.cpp'
1093
`.cxx'
1094
`.c++'
1095
     C++ source file
1096
 
1097
`.f'
1098
`.F'
1099
     Fortran source file
1100
 
1101
`.ch'
1102
`.c186'
1103
`.c286'
1104
     CHILL source file
1105
 
1106
`.mod'
1107
     Modula-2 source file
1108
 
1109
`.s'
1110
`.S'
1111
     Assembler source file.  This actually behaves almost like C, but
1112
     GDB does not skip over function prologues when stepping.
1113
 
1114
   In addition, you may set the language associated with a filename
1115
extension.  *Note Displaying the language: Show.
1116
 
1117

1118
File: gdb.info,  Node: Manually,  Next: Automatically,  Prev: Filenames,  Up: Setting
1119
 
1120
Setting the working language
1121
----------------------------
1122
 
1123
   If you allow GDB to set the language automatically, expressions are
1124
interpreted the same way in your debugging session and your program.
1125
 
1126
   If you wish, you may set the language manually.  To do this, issue
1127
the command `set language LANG', where LANG is the name of a language,
1128
such as `c' or `modula-2'.  For a list of the supported languages, type
1129
`set language'.
1130
 
1131
   Setting the language manually prevents GDB from updating the working
1132
language automatically.  This can lead to confusion if you try to debug
1133
a program when the working language is not the same as the source
1134
language, when an expression is acceptable to both languages--but means
1135
different things.  For instance, if the current source file were
1136
written in C, and GDB was parsing Modula-2, a command such as:
1137
 
1138
     print a = b + c
1139
 
1140
might not have the effect you intended.  In C, this means to add `b'
1141
and `c' and place the result in `a'.  The result printed would be the
1142
value of `a'.  In Modula-2, this means to compare `a' to the result of
1143
`b+c', yielding a `BOOLEAN' value.
1144
 
1145

1146
File: gdb.info,  Node: Automatically,  Prev: Manually,  Up: Setting
1147
 
1148
Having GDB infer the source language
1149
------------------------------------
1150
 
1151
   To have GDB set the working language automatically, use `set
1152
language local' or `set language auto'.  GDB then infers the working
1153
language.  That is, when your program stops in a frame (usually by
1154
encountering a breakpoint), GDB sets the working language to the
1155
language recorded for the function in that frame.  If the language for
1156
a frame is unknown (that is, if the function or block corresponding to
1157
the frame was defined in a source file that does not have a recognized
1158
extension), the current working language is not changed, and GDB issues
1159
a warning.
1160
 
1161
   This may not seem necessary for most programs, which are written
1162
entirely in one source language.  However, program modules and libraries
1163
written in one source language can be used by a main program written in
1164
a different source language.  Using `set language auto' in this case
1165
frees you from having to set the working language manually.
1166
 
1167

1168
File: gdb.info,  Node: Show,  Next: Checks,  Prev: Setting,  Up: Languages
1169
 
1170
Displaying the language
1171
=======================
1172
 
1173
   The following commands help you find out which language is the
1174
working language, and also what language source files were written in.
1175
 
1176
`show language'
1177
     Display the current working language.  This is the language you
1178
     can use with commands such as `print' to build and compute
1179
     expressions that may involve variables in your program.
1180
 
1181
`info frame'
1182
     Display the source language for this frame.  This language becomes
1183
     the working language if you use an identifier from this frame.
1184
     *Note Information about a frame: Frame Info, to identify the other
1185
     information listed here.
1186
 
1187
`info source'
1188
     Display the source language of this source file.  *Note Examining
1189
     the Symbol Table: Symbols, to identify the other information
1190
     listed here.
1191
 
1192
   In unusual circumstances, you may have source files with extensions
1193
not in the standard list.  You can then set the extension associated
1194
with a language explicitly:
1195
 
1196
`set extension-language .EXT LANGUAGE'
1197
     Set source files with extension .EXT to be assumed to be in the
1198
     source language LANGUAGE.
1199
 
1200
`info extensions'
1201
     List all the filename extensions and the associated languages.
1202
 
1203

1204
File: gdb.info,  Node: Checks,  Next: Support,  Prev: Show,  Up: Languages
1205
 
1206
Type and range checking
1207
=======================
1208
 
1209
     _Warning:_ In this release, the GDB commands for type and range
1210
     checking are included, but they do not yet have any effect.  This
1211
     section documents the intended facilities.
1212
 
1213
   Some languages are designed to guard you against making seemingly
1214
common errors through a series of compile- and run-time checks.  These
1215
include checking the type of arguments to functions and operators, and
1216
making sure mathematical overflows are caught at run time.  Checks such
1217
as these help to ensure a program's correctness once it has been
1218
compiled by eliminating type mismatches, and providing active checks
1219
for range errors when your program is running.
1220
 
1221
   GDB can check for conditions like the above if you wish.  Although
1222
GDB does not check the statements in your program, it can check
1223
expressions entered directly into GDB for evaluation via the `print'
1224
command, for example.  As with the working language, GDB can also
1225
decide whether or not to check automatically based on your program's
1226
source language.  *Note Supported languages: Support, for the default
1227
settings of supported languages.
1228
 
1229
* Menu:
1230
 
1231
* Type Checking::               An overview of type checking
1232
* Range Checking::              An overview of range checking
1233
 
1234

1235
File: gdb.info,  Node: Type Checking,  Next: Range Checking,  Up: Checks
1236
 
1237
An overview of type checking
1238
----------------------------
1239
 
1240
   Some languages, such as Modula-2, are strongly typed, meaning that
1241
the arguments to operators and functions have to be of the correct type,
1242
otherwise an error occurs.  These checks prevent type mismatch errors
1243
from ever causing any run-time problems.  For example,
1244
 
1245
     1 + 2 => 3
1246
but
1247
     error--> 1 + 2.3
1248
 
1249
   The second example fails because the `CARDINAL' 1 is not
1250
type-compatible with the `REAL' 2.3.
1251
 
1252
   For the expressions you use in GDB commands, you can tell the GDB
1253
type checker to skip checking; to treat any mismatches as errors and
1254
abandon the expression; or to only issue warnings when type mismatches
1255
occur, but evaluate the expression anyway.  When you choose the last of
1256
these, GDB evaluates expressions like the second example above, but
1257
also issues a warning.
1258
 
1259
   Even if you turn type checking off, there may be other reasons
1260
related to type that prevent GDB from evaluating an expression.  For
1261
instance, GDB does not know how to add an `int' and a `struct foo'.
1262
These particular type errors have nothing to do with the language in
1263
use, and usually arise from expressions, such as the one described
1264
above, which make little sense to evaluate anyway.
1265
 
1266
   Each language defines to what degree it is strict about type.  For
1267
instance, both Modula-2 and C require the arguments to arithmetical
1268
operators to be numbers.  In C, enumerated types and pointers can be
1269
represented as numbers, so that they are valid arguments to mathematical
1270
operators.  *Note Supported languages: Support, for further details on
1271
specific languages.
1272
 
1273
   GDB provides some additional commands for controlling the type
1274
checker:
1275
 
1276
`set check type auto'
1277
     Set type checking on or off based on the current working language.
1278
     *Note Supported languages: Support, for the default settings for
1279
     each language.
1280
 
1281
`set check type on'
1282
`set check type off'
1283
     Set type checking on or off, overriding the default setting for the
1284
     current working language.  Issue a warning if the setting does not
1285
     match the language default.  If any type mismatches occur in
1286
     evaluating an expression while type checking is on, GDB prints a
1287
     message and aborts evaluation of the expression.
1288
 
1289
`set check type warn'
1290
     Cause the type checker to issue warnings, but to always attempt to
1291
     evaluate the expression.  Evaluating the expression may still be
1292
     impossible for other reasons.  For example, GDB cannot add numbers
1293
     and structures.
1294
 
1295
`show type'
1296
     Show the current setting of the type checker, and whether or not
1297
     GDB is setting it automatically.
1298
 

powered by: WebSVN 2.1.0

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