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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [doc/] [gdb.info-6] - Blame information for rev 578

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

Line No. Rev Author Line
1 578 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2
 
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 Ninth Edition, April 2001, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 20010707.
12
 
13
   Copyright (C)
14
1988,1989,1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001
15
Free Software Foundation, Inc.
16
 
17
   Permission is granted to copy, distribute and/or modify this document
18
under the terms of the GNU Free Documentation License, Version 1.1 or
19
any later version published by the Free Software Foundation; with the
20
Invariant Sections being "A Sample GDB Session" and "Free Software",
21
with the Front-Cover texts being "A GNU Manual," and with the
22
Back-Cover Texts as in (a) below.
23
 
24
   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
25
modify this GNU Manual, like GNU software.  Copies published by the Free
26
Software Foundation raise funds for GNU development."
27
 
28

29
File: gdb.info,  Node: Built-In Func/Proc,  Next: M2 Constants,  Prev: M2 Operators,  Up: Modula-2
30
 
31
Built-in functions and procedures
32
.................................
33
 
34
   Modula-2 also makes available several built-in procedures and
35
functions.  In describing these, the following metavariables are used:
36
 
37
A
38
     represents an `ARRAY' variable.
39
 
40
C
41
     represents a `CHAR' constant or variable.
42
 
43
I
44
     represents a variable or constant of integral type.
45
 
46
M
47
     represents an identifier that belongs to a set.  Generally used in
48
     the same function with the metavariable S.  The type of S should
49
     be `SET OF MTYPE' (where MTYPE is the type of M).
50
 
51
N
52
     represents a variable or constant of integral or floating-point
53
     type.
54
 
55
R
56
     represents a variable or constant of floating-point type.
57
 
58
T
59
     represents a type.
60
 
61
V
62
     represents a variable.
63
 
64
X
65
     represents a variable or constant of one of many types.  See the
66
     explanation of the function for details.
67
 
68
   All Modula-2 built-in procedures also return a result, described
69
below.
70
 
71
`ABS(N)'
72
     Returns the absolute value of N.
73
 
74
`CAP(C)'
75
     If C is a lower case letter, it returns its upper case equivalent,
76
     otherwise it returns its argument.
77
 
78
`CHR(I)'
79
     Returns the character whose ordinal value is I.
80
 
81
`DEC(V)'
82
     Decrements the value in the variable V by one.  Returns the new
83
     value.
84
 
85
`DEC(V,I)'
86
     Decrements the value in the variable V by I.  Returns the new
87
     value.
88
 
89
`EXCL(M,S)'
90
     Removes the element M from the set S.  Returns the new set.
91
 
92
`FLOAT(I)'
93
     Returns the floating point equivalent of the integer I.
94
 
95
`HIGH(A)'
96
     Returns the index of the last member of A.
97
 
98
`INC(V)'
99
     Increments the value in the variable V by one.  Returns the new
100
     value.
101
 
102
`INC(V,I)'
103
     Increments the value in the variable V by I.  Returns the new
104
     value.
105
 
106
`INCL(M,S)'
107
     Adds the element M to the set S if it is not already there.
108
     Returns the new set.
109
 
110
`MAX(T)'
111
     Returns the maximum value of the type T.
112
 
113
`MIN(T)'
114
     Returns the minimum value of the type T.
115
 
116
`ODD(I)'
117
     Returns boolean TRUE if I is an odd number.
118
 
119
`ORD(X)'
120
     Returns the ordinal value of its argument.  For example, the
121
     ordinal value of a character is its ASCII value (on machines
122
     supporting the ASCII character set).  X must be of an ordered
123
     type, which include integral, character and enumerated types.
124
 
125
`SIZE(X)'
126
     Returns the size of its argument.  X can be a variable or a type.
127
 
128
`TRUNC(R)'
129
     Returns the integral part of R.
130
 
131
`VAL(T,I)'
132
     Returns the member of the type T whose ordinal value is I.
133
 
134
     _Warning:_  Sets and their operations are not yet supported, so
135
     GDB treats the use of procedures `INCL' and `EXCL' as an error.
136
 
137

138
File: gdb.info,  Node: M2 Constants,  Next: M2 Defaults,  Prev: Built-In Func/Proc,  Up: Modula-2
139
 
140
Constants
141
.........
142
 
143
   GDB allows you to express the constants of Modula-2 in the following
144
ways:
145
 
146
   * Integer constants are simply a sequence of digits.  When used in an
147
     expression, a constant is interpreted to be type-compatible with
148
     the rest of the expression.  Hexadecimal integers are specified by
149
     a trailing `H', and octal integers by a trailing `B'.
150
 
151
   * Floating point constants appear as a sequence of digits, followed
152
     by a decimal point and another sequence of digits.  An optional
153
     exponent can then be specified, in the form `E[+|-]NNN', where
154
     `[+|-]NNN' is the desired exponent.  All of the digits of the
155
     floating point constant must be valid decimal (base 10) digits.
156
 
157
   * Character constants consist of a single character enclosed by a
158
     pair of like quotes, either single (`'') or double (`"').  They may
159
     also be expressed by their ordinal value (their ASCII value,
160
     usually) followed by a `C'.
161
 
162
   * String constants consist of a sequence of characters enclosed by a
163
     pair of like quotes, either single (`'') or double (`"').  Escape
164
     sequences in the style of C are also allowed.  *Note C and C++
165
     constants: C Constants, for a brief explanation of escape
166
     sequences.
167
 
168
   * Enumerated constants consist of an enumerated identifier.
169
 
170
   * Boolean constants consist of the identifiers `TRUE' and `FALSE'.
171
 
172
   * Pointer constants consist of integral values only.
173
 
174
   * Set constants are not yet supported.
175
 
176

177
File: gdb.info,  Node: M2 Defaults,  Next: Deviations,  Prev: M2 Constants,  Up: Modula-2
178
 
179
Modula-2 defaults
180
.................
181
 
182
   If type and range checking are set automatically by GDB, they both
183
default to `on' whenever the working language changes to Modula-2.
184
This happens regardless of whether you or GDB selected the working
185
language.
186
 
187
   If you allow GDB to set the language automatically, then entering
188
code compiled from a file whose name ends with `.mod' sets the working
189
language to Modula-2.  *Note Having GDB set the language automatically:
190
Automatically, for further details.
191
 
192

193
File: gdb.info,  Node: Deviations,  Next: M2 Checks,  Prev: M2 Defaults,  Up: Modula-2
194
 
195
Deviations from standard Modula-2
196
.................................
197
 
198
   A few changes have been made to make Modula-2 programs easier to
199
debug.  This is done primarily via loosening its type strictness:
200
 
201
   * Unlike in standard Modula-2, pointer constants can be formed by
202
     integers.  This allows you to modify pointer variables during
203
     debugging.  (In standard Modula-2, the actual address contained in
204
     a pointer variable is hidden from you; it can only be modified
205
     through direct assignment to another pointer variable or
206
     expression that returned a pointer.)
207
 
208
   * C escape sequences can be used in strings and characters to
209
     represent non-printable characters.  GDB prints out strings with
210
     these escape sequences embedded.  Single non-printable characters
211
     are printed using the `CHR(NNN)' format.
212
 
213
   * The assignment operator (`:=') returns the value of its right-hand
214
     argument.
215
 
216
   * All built-in procedures both modify _and_ return their argument.
217
 
218

219
File: gdb.info,  Node: M2 Checks,  Next: M2 Scope,  Prev: Deviations,  Up: Modula-2
220
 
221
Modula-2 type and range checks
222
..............................
223
 
224
     _Warning:_ in this release, GDB does not yet perform type or range
225
     checking.
226
 
227
   GDB considers two Modula-2 variables type equivalent if:
228
 
229
   * They are of types that have been declared equivalent via a `TYPE
230
     T1 = T2' statement
231
 
232
   * They have been declared on the same line.  (Note:  This is true of
233
     the GNU Modula-2 compiler, but it may not be true of other
234
     compilers.)
235
 
236
   As long as type checking is enabled, any attempt to combine variables
237
whose types are not equivalent is an error.
238
 
239
   Range checking is done on all mathematical operations, assignment,
240
array index bounds, and all built-in functions and procedures.
241
 
242

243
File: gdb.info,  Node: M2 Scope,  Next: GDB/M2,  Prev: M2 Checks,  Up: Modula-2
244
 
245
The scope operators `::' and `.'
246
................................
247
 
248
   There are a few subtle differences between the Modula-2 scope
249
operator (`.') and the GDB scope operator (`::').  The two have similar
250
syntax:
251
 
252
 
253
     MODULE . ID
254
     SCOPE :: ID
255
 
256
where SCOPE is the name of a module or a procedure, MODULE the name of
257
a module, and ID is any declared identifier within your program, except
258
another module.
259
 
260
   Using the `::' operator makes GDB search the scope specified by
261
SCOPE for the identifier ID.  If it is not found in the specified
262
scope, then GDB searches all scopes enclosing the one specified by
263
SCOPE.
264
 
265
   Using the `.' operator makes GDB search the current scope for the
266
identifier specified by ID that was imported from the definition module
267
specified by MODULE.  With this operator, it is an error if the
268
identifier ID was not imported from definition module MODULE, or if ID
269
is not an identifier in MODULE.
270
 
271

272
File: gdb.info,  Node: GDB/M2,  Prev: M2 Scope,  Up: Modula-2
273
 
274
GDB and Modula-2
275
................
276
 
277
   Some GDB commands have little use when debugging Modula-2 programs.
278
Five subcommands of `set print' and `show print' apply specifically to
279
C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'.
280
The first four apply to C++, and the last to the C `union' type, which
281
has no direct analogue in Modula-2.
282
 
283
   The `@' operator (*note Expressions: Expressions.), while available
284
with any language, is not useful with Modula-2.  Its intent is to aid
285
the debugging of "dynamic arrays", which cannot be created in Modula-2
286
as they can in C or C++.  However, because an address can be specified
287
by an integral constant, the construct `{TYPE}ADREXP' is still useful.
288
 
289
   In GDB scripts, the Modula-2 inequality operator `#' is interpreted
290
as the beginning of a comment.  Use `<>' instead.
291
 
292

293
File: gdb.info,  Node: Chill,  Prev: Modula-2,  Up: Support
294
 
295
Chill
296
-----
297
 
298
   The extensions made to GDB to support Chill only support output from
299
the GNU Chill compiler.  Other Chill compilers are not currently
300
supported, and attempting to debug executables produced by them is most
301
likely to give an error as GDB reads in the executable's symbol table.
302
 
303
   This section covers the Chill related topics and the features of GDB
304
which support these topics.
305
 
306
* Menu:
307
 
308
* How modes are displayed::        How modes are displayed
309
* Locations::                        Locations and their accesses
310
* Values and their Operations:: Values and their Operations
311
* Chill type and range checks::
312
* Chill defaults::
313
 
314

315
File: gdb.info,  Node: How modes are displayed,  Next: Locations,  Up: Chill
316
 
317
How modes are displayed
318
.......................
319
 
320
   The Chill Datatype- (Mode) support of GDB is directly related with
321
the functionality of the GNU Chill compiler, and therefore deviates
322
slightly from the standard specification of the Chill language. The
323
provided modes are:
324
 
325
`_Discrete modes:_'
326
        * _Integer Modes_ which are predefined by `BYTE, UBYTE, INT,
327
          UINT, LONG, ULONG',
328
 
329
        * _Boolean Mode_ which is predefined by `BOOL',
330
 
331
        * _Character Mode_ which is predefined by `CHAR',
332
 
333
        * _Set Mode_ which is displayed by the keyword `SET'.
334
               (gdb) ptype x
335
               type = SET (karli = 10, susi = 20, fritzi = 100)
336
          If the type is an unnumbered set the set element values are
337
          omitted.
338
 
339
        * _Range Mode_ which is displayed by
340
               `type = ( : )'
341
          where `, ' can be of any discrete
342
          literal expression (e.g. set element names).
343
 
344
`_Powerset Mode:_'
345
     A Powerset Mode is displayed by the keyword `POWERSET' followed by
346
     the member mode of the powerset.  The member mode can be any
347
     discrete mode.
348
          (gdb) ptype x
349
          type = POWERSET SET (egon, hugo, otto)
350
 
351
`_Reference Modes:_'
352
        * _Bound Reference Mode_ which is displayed by the keyword `REF'
353
          followed by the mode name to which the reference is bound.
354
 
355
        * _Free Reference Mode_ which is displayed by the keyword `PTR'.
356
 
357
`_Procedure mode_'
358
     The procedure mode is displayed by `type = PROC()
359
      EXCEPTIONS ()'. The `
360
     list>' is a list of the parameter modes.  `' indicates
361
     the mode of the result of the procedure if any.  The exceptionlist
362
     lists all possible exceptions which can be raised by the procedure.
363
 
364
`_Synchronization Modes:_'
365
        * _Event Mode_ which is displayed by
366
               `EVENT ()'
367
          where `()' is optional.
368
 
369
        * _Buffer Mode_ which is displayed by
370
               `BUFFER ()'
371
          where `()' is optional.
372
 
373
`_Timing Modes:_'
374
        * _Duration Mode_ which is predefined by `DURATION'
375
 
376
        * _Absolute Time Mode_ which is predefined by `TIME'
377
 
378
`_Real Modes:_'
379
     Real Modes are predefined with `REAL' and `LONG_REAL'.
380
 
381
`_String Modes:_'
382
        * _Character String Mode_ which is displayed by
383
               `CHARS()'
384
          followed by the keyword `VARYING' if the String Mode is a
385
          varying mode
386
 
387
        * _Bit String Mode_ which is displayed by
388
               `BOOLS(
389
               length>)'
390
 
391
`_Array Mode:_'
392
     The Array Mode is displayed by the keyword `ARRAY()'
393
     followed by the element mode (which may in turn be an array mode).
394
          (gdb) ptype x
395
          type = ARRAY (1:42)
396
                    ARRAY (1:20)
397
                       SET (karli = 10, susi = 20, fritzi = 100)
398
 
399
`_Structure Mode_'
400
     The Structure mode is displayed by the keyword `STRUCT(
401
     list>)'.  The `' consists of names and modes of fields
402
     of the structure.  Variant structures have the keyword `CASE
403
      OF  ESAC' in their field list.  Since the
404
     current version of the GNU Chill compiler doesn't implement tag
405
     processing (no runtime checks of variant fields, and therefore no
406
     debugging info), the output always displays all variant fields.
407
          (gdb) ptype str
408
          type = STRUCT (
409
              as x,
410
              bs x,
411
              CASE bs OF
412
              (karli):
413
                  cs a
414
              (ott):
415
                  ds x
416
              ESAC
417
          )
418
 
419

420
File: gdb.info,  Node: Locations,  Next: Values and their Operations,  Prev: How modes are displayed,  Up: Chill
421
 
422
Locations and their accesses
423
............................
424
 
425
   A location in Chill is an object which can contain values.
426
 
427
   A value of a location is generally accessed by the (declared) name of
428
the location.  The output conforms to the specification of values in
429
Chill programs.  How values are specified is the topic of the next
430
section, *Note Values and their Operations::.
431
 
432
   The pseudo-location `RESULT' (or `result') can be used to display or
433
change the result of a currently-active procedure:
434
 
435
     set result := EXPR
436
 
437
This does the same as the Chill action `RESULT EXPR' (which is not
438
available in GDB).
439
 
440
   Values of reference mode locations are printed by `PTR()'
441
in case of a free reference mode, and by `(REF )
442
()' in case of a bound reference.  `' represents
443
the address where the reference points to.  To access the value of the
444
location referenced by the pointer, use the dereference operator `->'.
445
 
446
   Values of procedure mode locations are displayed by
447
     `{ PROC
448
     ( )  } 
449
     location>'
450
   `' is a list of modes according to the parameter
451
specification of the procedure and `
' shows the address of the
452
entry point.
453
 
454
   Substructures of string mode-, array mode- or structure mode-values
455
(e.g. array slices, fields of structure locations) are accessed using
456
certain operations which are described in the next section, *Note
457
Values and their Operations::.
458
 
459
   A location value may be interpreted as having a different mode using
460
the location conversion.  This mode conversion is written as `
461
name>()'.  The user has to consider that the sizes of the
462
modes have to be equal otherwise an error occurs.  Furthermore, no range
463
checking of the location against the destination mode is performed, and
464
therefore the result can be quite confusing.
465
 
466
     (gdb) print int (s(3 up 4)) XXX TO be filled in !! XXX
467
 
468

469
File: gdb.info,  Node: Values and their Operations,  Next: Chill type and range checks,  Prev: Locations,  Up: Chill
470
 
471
Values and their Operations
472
...........................
473
 
474
   Values are used to alter locations, to investigate complex
475
structures in more detail or to filter relevant information out of a
476
large amount of data.  There are several (mode dependent) operations
477
defined which enable such investigations.  These operations are not
478
only applicable to constant values but also to locations, which can
479
become quite useful when debugging complex structures.  During parsing
480
the command line (e.g. evaluating an expression) GDB treats location
481
names as the values behind these locations.
482
 
483
   This section describes how values have to be specified and which
484
operations are legal to be used with such values.
485
 
486
`Literal Values'
487
     Literal values are specified in the same manner as in GNU Chill
488
     programs.  For detailed specification refer to the GNU Chill
489
     implementation Manual chapter 1.5.
490
 
491
`Tuple Values'
492
     A tuple is specified by `[]', where `
493
     name>' can be omitted if the mode of the tuple is unambiguous.
494
     This unambiguity is derived from the context of a evaluated
495
     expression.  `' can be one of the following:
496
 
497
        * _Powerset Tuple_
498
 
499
        * _Array Tuple_
500
 
501
        * _Structure Tuple_ Powerset tuples, array tuples and structure
502
          tuples are specified in the same manner as in Chill programs
503
          refer to z200/88 chpt 5.2.5.
504
 
505
`String Element Value'
506
     A string element value is specified by
507
          `()'
508
     where `' is a integer expression.  It delivers a character
509
     value which is equivalent to the character indexed by `' in
510
     the string.
511
 
512
`String Slice Value'
513
     A string slice value is specified by `(
514
     spec>)', where `' can be either a range of integer
515
     expressions or specified by ` up '.  `'
516
     denotes the number of elements which the slice contains.  The
517
     delivered value is a string value, which is part of the specified
518
     string.
519
 
520
`Array Element Values'
521
     An array element value is specified by `()' and
522
     delivers a array element value of the mode of the specified array.
523
 
524
`Array Slice Values'
525
     An array slice is specified by `()', where
526
     `' can be either a range specified by expressions or by
527
     ` up '.  `' denotes the number of
528
     arrayelements the slice contains.  The delivered value is an array
529
     value which is part of the specified array.
530
 
531
`Structure Field Values'
532
     A structure field value is derived by `.
533
     name>', where `' indicates the name of a field
534
     specified in the mode definition of the structure.  The mode of
535
     the delivered value corresponds to this mode definition in the
536
     structure definition.
537
 
538
`Procedure Call Value'
539
     The procedure call value is derived from the return value of the
540
     procedure(1).
541
 
542
     Values of duration mode locations are represented by `ULONG'
543
     literals.
544
 
545
     Values of time mode locations appear as
546
          `TIME(:)'
547
 
548
`Zero-adic Operator Value'
549
     The zero-adic operator value is derived from the instance value
550
     for the current active process.
551
 
552
`Expression Values'
553
     The value delivered by an expression is the result of the
554
     evaluation of the specified expression.  If there are error
555
     conditions (mode incompatibility, etc.) the evaluation of
556
     expressions is aborted with a corresponding error message.
557
     Expressions may be parenthesised which causes the evaluation of
558
     this expression before any other expression which uses the result
559
     of the parenthesised expression.  The following operators are
560
     supported by GDB:
561
 
562
    ``OR, ORIF, XOR''
563
    ``AND, ANDIF''
564
    ``NOT''
565
          Logical operators defined over operands of boolean mode.
566
 
567
    ``=, /=''
568
          Equality and inequality operators defined over all modes.
569
 
570
    ``>, >=''
571
    ``<, <=''
572
          Relational operators defined over predefined modes.
573
 
574
    ``+, -''
575
    ``*, /, MOD, REM''
576
          Arithmetic operators defined over predefined modes.
577
 
578
    ``-''
579
          Change sign operator.
580
 
581
    ``//''
582
          String concatenation operator.
583
 
584
    ``()''
585
          String repetition operator.
586
 
587
    ``->''
588
          Referenced location operator which can be used either to take
589
          the address of a location (`->loc'), or to dereference a
590
          reference location (`loc->').
591
 
592
    ``OR, XOR''
593
    ``AND''
594
    ``NOT''
595
          Powerset and bitstring operators.
596
 
597
    ``>, >=''
598
    ``<, <=''
599
          Powerset inclusion operators.
600
 
601
    ``IN''
602
          Membership operator.
603
 
604
   ---------- Footnotes ----------
605
 
606
   (1) If a procedure call is used for instance in an expression, then
607
this procedure is called with all its side effects.  This can lead to
608
confusing results if used carelessly.
609
 
610

611
File: gdb.info,  Node: Chill type and range checks,  Next: Chill defaults,  Prev: Values and their Operations,  Up: Chill
612
 
613
Chill type and range checks
614
...........................
615
 
616
   GDB considers two Chill variables mode equivalent if the sizes of
617
the two modes are equal.  This rule applies recursively to more complex
618
datatypes which means that complex modes are treated equivalent if all
619
element modes (which also can be complex modes like structures, arrays,
620
etc.) have the same size.
621
 
622
   Range checking is done on all mathematical operations, assignment,
623
array index bounds and all built in procedures.
624
 
625
   Strong type checks are forced using the GDB command `set check
626
strong'.  This enforces strong type and range checks on all operations
627
where Chill constructs are used (expressions, built in functions, etc.)
628
in respect to the semantics as defined in the z.200 language
629
specification.
630
 
631
   All checks can be disabled by the GDB command `set check off'.
632
 
633

634
File: gdb.info,  Node: Chill defaults,  Prev: Chill type and range checks,  Up: Chill
635
 
636
Chill defaults
637
..............
638
 
639
   If type and range checking are set automatically by GDB, they both
640
default to `on' whenever the working language changes to Chill.  This
641
happens regardless of whether you or GDB selected the working language.
642
 
643
   If you allow GDB to set the language automatically, then entering
644
code compiled from a file whose name ends with `.ch' sets the working
645
language to Chill.  *Note Having GDB set the language automatically:
646
Automatically, for further details.
647
 
648

649
File: gdb.info,  Node: Symbols,  Next: Altering,  Prev: Languages,  Up: Top
650
 
651
Examining the Symbol Table
652
**************************
653
 
654
   The commands described in this chapter allow you to inquire about the
655
symbols (names of variables, functions and types) defined in your
656
program.  This information is inherent in the text of your program and
657
does not change as your program executes.  GDB finds it in your
658
program's symbol table, in the file indicated when you started GDB
659
(*note Choosing files: File Options.), or by one of the file-management
660
commands (*note Commands to specify files: Files.).
661
 
662
   Occasionally, you may need to refer to symbols that contain unusual
663
characters, which GDB ordinarily treats as word delimiters.  The most
664
frequent case is in referring to static variables in other source files
665
(*note Program variables: Variables.).  File names are recorded in
666
object files as debugging symbols, but GDB would ordinarily parse a
667
typical file name, like `foo.c', as the three words `foo' `.' `c'.  To
668
allow GDB to recognize `foo.c' as a single symbol, enclose it in single
669
quotes; for example,
670
 
671
     p 'foo.c'::x
672
 
673
looks up the value of `x' in the scope of the file `foo.c'.
674
 
675
`info address SYMBOL'
676
     Describe where the data for SYMBOL is stored.  For a register
677
     variable, this says which register it is kept in.  For a
678
     non-register local variable, this prints the stack-frame offset at
679
     which the variable is always stored.
680
 
681
     Note the contrast with `print &SYMBOL', which does not work at all
682
     for a register variable, and for a stack local variable prints the
683
     exact address of the current instantiation of the variable.
684
 
685
`info symbol ADDR'
686
     Print the name of a symbol which is stored at the address ADDR.
687
     If no symbol is stored exactly at ADDR, GDB prints the nearest
688
     symbol and an offset from it:
689
 
690
          (gdb) info symbol 0x54320
691
          _initialize_vx + 396 in section .text
692
 
693
     This is the opposite of the `info address' command.  You can use
694
     it to find out the name of a variable or a function given its
695
     address.
696
 
697
`whatis EXPR'
698
     Print the data type of expression EXPR.  EXPR is not actually
699
     evaluated, and any side-effecting operations (such as assignments
700
     or function calls) inside it do not take place.  *Note
701
     Expressions: Expressions.
702
 
703
`whatis'
704
     Print the data type of `$', the last value in the value history.
705
 
706
`ptype TYPENAME'
707
     Print a description of data type TYPENAME.  TYPENAME may be the
708
     name of a type, or for C code it may have the form `class
709
     CLASS-NAME', `struct STRUCT-TAG', `union UNION-TAG' or `enum
710
     ENUM-TAG'.
711
 
712
`ptype EXPR'
713
`ptype'
714
     Print a description of the type of expression EXPR.  `ptype'
715
     differs from `whatis' by printing a detailed description, instead
716
     of just the name of the type.
717
 
718
     For example, for this variable declaration:
719
 
720
          struct complex {double real; double imag;} v;
721
 
722
     the two commands give this output:
723
 
724
          (gdb) whatis v
725
          type = struct complex
726
          (gdb) ptype v
727
          type = struct complex {
728
              double real;
729
              double imag;
730
          }
731
 
732
     As with `whatis', using `ptype' without an argument refers to the
733
     type of `$', the last value in the value history.
734
 
735
`info types REGEXP'
736
`info types'
737
     Print a brief description of all types whose names match REGEXP
738
     (or all types in your program, if you supply no argument).  Each
739
     complete typename is matched as though it were a complete line;
740
     thus, `i type value' gives information on all types in your
741
     program whose names include the string `value', but `i type
742
     ^value$' gives information only on types whose complete name is
743
     `value'.
744
 
745
     This command differs from `ptype' in two ways: first, like
746
     `whatis', it does not print a detailed description; second, it
747
     lists all source files where a type is defined.
748
 
749
`info scope ADDR'
750
     List all the variables local to a particular scope.  This command
751
     accepts a location--a function name, a source line, or an address
752
     preceded by a `*', and prints all the variables local to the scope
753
     defined by that location.  For example:
754
 
755
          (gdb) info scope command_line_handler
756
          Scope for command_line_handler:
757
          Symbol rl is an argument at stack/frame offset 8, length 4.
758
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
759
          Symbol linelength is in static storage at address 0x150a1c, length 4.
760
          Symbol p is a local variable in register $esi, length 4.
761
          Symbol p1 is a local variable in register $ebx, length 4.
762
          Symbol nline is a local variable in register $edx, length 4.
763
          Symbol repeat is a local variable at frame offset -8, length 4.
764
 
765
     This command is especially useful for determining what data to
766
     collect during a "trace experiment", see *Note collect: Tracepoint
767
     Actions.
768
 
769
`info source'
770
     Show the name of the current source file--that is, the source file
771
     for the function containing the current point of execution--and
772
     the language it was written in.
773
 
774
`info sources'
775
     Print the names of all source files in your program for which
776
     there is debugging information, organized into two lists: files
777
     whose symbols have already been read, and files whose symbols will
778
     be read when needed.
779
 
780
`info functions'
781
     Print the names and data types of all defined functions.
782
 
783
`info functions REGEXP'
784
     Print the names and data types of all defined functions whose
785
     names contain a match for regular expression REGEXP.  Thus, `info
786
     fun step' finds all functions whose names include `step'; `info
787
     fun ^step' finds those whose names start with `step'.
788
 
789
`info variables'
790
     Print the names and data types of all variables that are declared
791
     outside of functions (i.e., excluding local variables).
792
 
793
`info variables REGEXP'
794
     Print the names and data types of all variables (except for local
795
     variables) whose names contain a match for regular expression
796
     REGEXP.
797
 
798
     Some systems allow individual object files that make up your
799
     program to be replaced without stopping and restarting your
800
     program.  For example, in VxWorks you can simply recompile a
801
     defective object file and keep on running.  If you are running on
802
     one of these systems, you can allow GDB to reload the symbols for
803
     automatically relinked modules:
804
 
805
    `set symbol-reloading on'
806
          Replace symbol definitions for the corresponding source file
807
          when an object file with a particular name is seen again.
808
 
809
    `set symbol-reloading off'
810
          Do not replace symbol definitions when encountering object
811
          files of the same name more than once.  This is the default
812
          state; if you are not running on a system that permits
813
          automatic relinking of modules, you should leave
814
          `symbol-reloading' off, since otherwise GDB may discard
815
          symbols when linking large programs, that may contain several
816
          modules (from different directories or libraries) with the
817
          same name.
818
 
819
    `show symbol-reloading'
820
          Show the current `on' or `off' setting.
821
 
822
`set opaque-type-resolution on'
823
     Tell GDB to resolve opaque types.  An opaque type is a type
824
     declared as a pointer to a `struct', `class', or `union'--for
825
     example, `struct MyType *'--that is used in one source file
826
     although the full declaration of `struct MyType' is in another
827
     source file.  The default is on.
828
 
829
     A change in the setting of this subcommand will not take effect
830
     until the next time symbols for a file are loaded.
831
 
832
`set opaque-type-resolution off'
833
     Tell GDB not to resolve opaque types.  In this case, the type is
834
     printed as follows:
835
          {}
836
 
837
`show opaque-type-resolution'
838
     Show whether opaque types are resolved or not.
839
 
840
`maint print symbols FILENAME'
841
`maint print psymbols FILENAME'
842
`maint print msymbols FILENAME'
843
     Write a dump of debugging symbol data into the file FILENAME.
844
     These commands are used to debug the GDB symbol-reading code.  Only
845
     symbols with debugging data are included.  If you use `maint print
846
     symbols', GDB includes all the symbols for which it has already
847
     collected full details: that is, FILENAME reflects symbols for
848
     only those files whose symbols GDB has read.  You can use the
849
     command `info sources' to find out which files these are.  If you
850
     use `maint print psymbols' instead, the dump shows information
851
     about symbols that GDB only knows partially--that is, symbols
852
     defined in files that GDB has skimmed, but not yet read
853
     completely.  Finally, `maint print msymbols' dumps just the
854
     minimal symbol information required for each object file from
855
     which GDB has read some symbols.  *Note Commands to specify files:
856
     Files, for a discussion of how GDB reads symbols (in the
857
     description of `symbol-file').
858
 
859

860
File: gdb.info,  Node: Altering,  Next: GDB Files,  Prev: Symbols,  Up: Top
861
 
862
Altering Execution
863
******************
864
 
865
   Once you think you have found an error in your program, you might
866
want to find out for certain whether correcting the apparent error
867
would lead to correct results in the rest of the run.  You can find the
868
answer by experiment, using the GDB features for altering execution of
869
the program.
870
 
871
   For example, you can store new values into variables or memory
872
locations, give your program a signal, restart it at a different
873
address, or even return prematurely from a function.
874
 
875
* Menu:
876
 
877
* Assignment::                  Assignment to variables
878
* Jumping::                     Continuing at a different address
879
* Signaling::                   Giving your program a signal
880
* Returning::                   Returning from a function
881
* Calling::                     Calling your program's functions
882
* Patching::                    Patching your program
883
 
884

885
File: gdb.info,  Node: Assignment,  Next: Jumping,  Up: Altering
886
 
887
Assignment to variables
888
=======================
889
 
890
   To alter the value of a variable, evaluate an assignment expression.
891
*Note Expressions: Expressions.  For example,
892
 
893
     print x=4
894
 
895
stores the value 4 into the variable `x', and then prints the value of
896
the assignment expression (which is 4).  *Note Using GDB with Different
897
Languages: Languages, for more information on operators in supported
898
languages.
899
 
900
   If you are not interested in seeing the value of the assignment, use
901
the `set' command instead of the `print' command.  `set' is really the
902
same as `print' except that the expression's value is not printed and
903
is not put in the value history (*note Value history: Value History.).
904
The expression is evaluated only for its effects.
905
 
906
   If the beginning of the argument string of the `set' command appears
907
identical to a `set' subcommand, use the `set variable' command instead
908
of just `set'.  This command is identical to `set' except for its lack
909
of subcommands.  For example, if your program has a variable `width',
910
you get an error if you try to set a new value with just `set
911
width=13', because GDB has the command `set width':
912
 
913
     (gdb) whatis width
914
     type = double
915
     (gdb) p width
916
     $4 = 13
917
     (gdb) set width=47
918
     Invalid syntax in expression.
919
 
920
The invalid expression, of course, is `=47'.  In order to actually set
921
the program's variable `width', use
922
 
923
     (gdb) set var width=47
924
 
925
   Because the `set' command has many subcommands that can conflict
926
with the names of program variables, it is a good idea to use the `set
927
variable' command instead of just `set'.  For example, if your program
928
has a variable `g', you run into problems if you try to set a new value
929
with just `set g=4', because GDB has the command `set gnutarget',
930
abbreviated `set g':
931
 
932
     (gdb) whatis g
933
     type = double
934
     (gdb) p g
935
     $1 = 1
936
     (gdb) set g=4
937
     (gdb) p g
938
     $2 = 1
939
     (gdb) r
940
     The program being debugged has been started already.
941
     Start it from the beginning? (y or n) y
942
     Starting program: /home/smith/cc_progs/a.out
943
     "/home/smith/cc_progs/a.out": can't open to read symbols:
944
                                      Invalid bfd target.
945
     (gdb) show g
946
     The current BFD target is "=4".
947
 
948
The program variable `g' did not change, and you silently set the
949
`gnutarget' to an invalid value.  In order to set the variable `g', use
950
 
951
     (gdb) set var g=4
952
 
953
   GDB allows more implicit conversions in assignments than C; you can
954
freely store an integer value into a pointer variable or vice versa,
955
and you can convert any structure to any other structure that is the
956
same length or shorter.
957
 
958
   To store values into arbitrary places in memory, use the `{...}'
959
construct to generate a value of specified type at a specified address
960
(*note Expressions: Expressions.).  For example, `{int}0x83040' refers
961
to memory location `0x83040' as an integer (which implies a certain size
962
and representation in memory), and
963
 
964
     set {int}0x83040 = 4
965
 
966
stores the value 4 into that memory location.
967
 
968

969
File: gdb.info,  Node: Jumping,  Next: Signaling,  Prev: Assignment,  Up: Altering
970
 
971
Continuing at a different address
972
=================================
973
 
974
   Ordinarily, when you continue your program, you do so at the place
975
where it stopped, with the `continue' command.  You can instead
976
continue at an address of your own choosing, with the following
977
commands:
978
 
979
`jump LINESPEC'
980
     Resume execution at line LINESPEC.  Execution stops again
981
     immediately if there is a breakpoint there.  *Note Printing source
982
     lines: List, for a description of the different forms of LINESPEC.
983
     It is common practice to use the `tbreak' command in conjunction
984
     with `jump'.  *Note Setting breakpoints: Set Breaks.
985
 
986
     The `jump' command does not change the current stack frame, or the
987
     stack pointer, or the contents of any memory location or any
988
     register other than the program counter.  If line LINESPEC is in a
989
     different function from the one currently executing, the results
990
     may be bizarre if the two functions expect different patterns of
991
     arguments or of local variables.  For this reason, the `jump'
992
     command requests confirmation if the specified line is not in the
993
     function currently executing.  However, even bizarre results are
994
     predictable if you are well acquainted with the machine-language
995
     code of your program.
996
 
997
`jump *ADDRESS'
998
     Resume execution at the instruction at address ADDRESS.
999
 
1000
   On many systems, you can get much the same effect as the `jump'
1001
command by storing a new value into the register `$pc'.  The difference
1002
is that this does not start your program running; it only changes the
1003
address of where it _will_ run when you continue.  For example,
1004
 
1005
     set $pc = 0x485
1006
 
1007
makes the next `continue' command or stepping command execute at
1008
address `0x485', rather than at the address where your program stopped.
1009
*Note Continuing and stepping: Continuing and Stepping.
1010
 
1011
   The most common occasion to use the `jump' command is to back
1012
up--perhaps with more breakpoints set--over a portion of a program that
1013
has already executed, in order to examine its execution in more detail.
1014
 
1015

1016
File: gdb.info,  Node: Signaling,  Next: Returning,  Prev: Jumping,  Up: Altering
1017
 
1018
Giving your program a signal
1019
============================
1020
 
1021
`signal SIGNAL'
1022
     Resume execution where your program stopped, but immediately give
1023
     it the signal SIGNAL.  SIGNAL can be the name or the number of a
1024
     signal.  For example, on many systems `signal 2' and `signal
1025
     SIGINT' are both ways of sending an interrupt signal.
1026
 
1027
     Alternatively, if SIGNAL is zero, continue execution without
1028
     giving a signal.  This is useful when your program stopped on
1029
     account of a signal and would ordinary see the signal when resumed
1030
     with the `continue' command; `signal 0' causes it to resume
1031
     without a signal.
1032
 
1033
     `signal' does not repeat when you press  a second time after
1034
     executing the command.
1035
 
1036
   Invoking the `signal' command is not the same as invoking the `kill'
1037
utility from the shell.  Sending a signal with `kill' causes GDB to
1038
decide what to do with the signal depending on the signal handling
1039
tables (*note Signals::).  The `signal' command passes the signal
1040
directly to your program.
1041
 
1042

1043
File: gdb.info,  Node: Returning,  Next: Calling,  Prev: Signaling,  Up: Altering
1044
 
1045
Returning from a function
1046
=========================
1047
 
1048
`return'
1049
`return EXPRESSION'
1050
     You can cancel execution of a function call with the `return'
1051
     command.  If you give an EXPRESSION argument, its value is used as
1052
     the function's return value.
1053
 
1054
   When you use `return', GDB discards the selected stack frame (and
1055
all frames within it).  You can think of this as making the discarded
1056
frame return prematurely.  If you wish to specify a value to be
1057
returned, give that value as the argument to `return'.
1058
 
1059
   This pops the selected stack frame (*note Selecting a frame:
1060
Selection.), and any other frames inside of it, leaving its caller as
1061
the innermost remaining frame.  That frame becomes selected.  The
1062
specified value is stored in the registers used for returning values of
1063
functions.
1064
 
1065
   The `return' command does not resume execution; it leaves the
1066
program stopped in the state that would exist if the function had just
1067
returned.  In contrast, the `finish' command (*note Continuing and
1068
stepping: Continuing and Stepping.) resumes execution until the
1069
selected stack frame returns naturally.
1070
 
1071

1072
File: gdb.info,  Node: Calling,  Next: Patching,  Prev: Returning,  Up: Altering
1073
 
1074
Calling program functions
1075
=========================
1076
 
1077
`call EXPR'
1078
     Evaluate the expression EXPR without displaying `void' returned
1079
     values.
1080
 
1081
   You can use this variant of the `print' command if you want to
1082
execute a function from your program, but without cluttering the output
1083
with `void' returned values.  If the result is not void, it is printed
1084
and saved in the value history.
1085
 
1086
   For the A29K, a user-controlled variable `call_scratch_address',
1087
specifies the location of a scratch area to be used when GDB calls a
1088
function in the target.  This is necessary because the usual method of
1089
putting the scratch area on the stack does not work in systems that
1090
have separate instruction and data spaces.
1091
 
1092

1093
File: gdb.info,  Node: Patching,  Prev: Calling,  Up: Altering
1094
 
1095
Patching programs
1096
=================
1097
 
1098
   By default, GDB opens the file containing your program's executable
1099
code (or the corefile) read-only.  This prevents accidental alterations
1100
to machine code; but it also prevents you from intentionally patching
1101
your program's binary.
1102
 
1103
   If you'd like to be able to patch the binary, you can specify that
1104
explicitly with the `set write' command.  For example, you might want
1105
to turn on internal debugging flags, or even to make emergency repairs.
1106
 
1107
`set write on'
1108
`set write off'
1109
     If you specify `set write on', GDB opens executable and core files
1110
     for both reading and writing; if you specify `set write off' (the
1111
     default), GDB opens them read-only.
1112
 
1113
     If you have already loaded a file, you must load it again (using
1114
     the `exec-file' or `core-file' command) after changing `set
1115
     write', for your new setting to take effect.
1116
 
1117
`show write'
1118
     Display whether executable files and core files are opened for
1119
     writing as well as reading.
1120
 
1121

1122
File: gdb.info,  Node: GDB Files,  Next: Targets,  Prev: Altering,  Up: Top
1123
 
1124
GDB Files
1125
*********
1126
 
1127
   GDB needs to know the file name of the program to be debugged, both
1128
in order to read its symbol table and in order to start your program.
1129
To debug a core dump of a previous run, you must also tell GDB the name
1130
of the core dump file.
1131
 
1132
* Menu:
1133
 
1134
* Files::                       Commands to specify files
1135
* Symbol Errors::               Errors reading symbol files
1136
 

powered by: WebSVN 2.1.0

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