![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gdb-2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info|
Return to gdb-2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info |
1.1 root 1: Info file gdb, produced by texinfo-format-buffer -*-Text-*-
2: from file gdb.texinfo
3:
4: This file documents the GNU debugger GDB.
5:
6: Copyright (C) 1988 Free Software Foundation, Inc.
7:
8: Permission is granted to make and distribute verbatim copies of
9: this manual provided the copyright notice and this permission notice
10: are preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of this
13: manual under the conditions for verbatim copying, provided also that the
14: sections entitled "Distribution" and "GDB General Public License" are
15: included exactly as in the original, and provided that the entire resulting
16: derived work is distributed under the terms of a permission notice
17: identical to this one.
18:
19: Permission is granted to copy and distribute translations of this manual
20: into another language, under the above conditions for modified versions,
21: except that the sections entitled "Distribution" and "GDB General Public
22: License" may be included in a translation approved by the author instead
23: of in the original English.
24:
25:
26:
27: File: gdb Node: Stack, Prev: Stopping, Up: Top, Next: Source
28:
29: Examining the Stack
30: *******************
31:
32: When your program has stopped, the first thing you need to know is where it
33: stopped and how it got there.
34:
35: Each time your program performs a function call, the information about
36: where in the program the call was made from is saved in a block of data
37: called a "stack frame". The frame also contains the arguments of the
38: call and the local variables of the function that was called. All the
39: stack frames are allocated in a region of memory called the "call
40: stack".
41:
42: When your program stops, the GDB commands for examining the stack allow you
43: to see all of this information.
44:
45: One of the stack frames is "selected" by GDB and many GDB commands
46: refer implicitly to the selected frame. In particular, whenever you ask
47: GDB for the value of a variable in the program, the value is found in the
48: selected frame. There are special GDB commands to select whichever frame
49: you are interested in.
50:
51: When the program stops, GDB automatically selects the currently executing
52: frame and describes it briefly as the `frame' command does
53: (*Note Info: Frame Info.).
54:
55: * Menu:
56:
57: * Frames:: Explanation of stack frames and terminology.
58: * Backtrace:: Summarizing many frames at once.
59: * Selection:: How to select a stack frame.
60: * Info: Frame Info, Commands to print information on stack frames.
61:
62:
63: File: gdb Node: Frames, Prev: Stack, Up: Stack, Next: Backtrace
64:
65: Stack Frames
66: ============
67:
68: The call stack is divided up into contiguous pieces called "frames";
69: each frame is the data associated with one call to one function. The frame
70: contains the arguments given to the function, the function's local
71: variables, and the address at which the function is executing.
72:
73: When your program is started, the stack has only one frame, that of the
74: function `main'. This is called the "initial" frame or the
75: "outermost" frame. Each time a function is called, a new frame is
76: made. Each time a function returns, the frame for that function invocation
77: is eliminated. If a function is recursive, there can be many frames for
78: the same function. The frame for the function in which execution is
79: actually occurring is called the "innermost" frame. This is the most
80: recently created of all the stack frames that still exist.
81:
82: Inside your program, stack frames are identified by their addresses. A
83: stack frame consists of many bytes, each of which has its own address; each
84: kind of computer has a convention for choosing one of those bytes whose
85: address serves as the address of the frame. Usually this address is kept
86: in a register called the "frame pointer register" while execution is
87: going on in that frame.
88:
89: GDB assigns numbers to all existing stack frames, starting with zero for
90: the innermost frame, one for the frame that called it, and so on upward.
91: These numbers do not really exist in your program; they are to give you a
92: way of talking about stack frames in GDB commands.
93:
94: Many GDB commands refer implicitly to one stack frame. GDB records a stack
95: frame that is called the "selected" stack frame; you can select any
96: frame using one set of GDB commands, and then other commands will operate
97: on that frame. When your program stops, GDB automatically selects the
98: innermost frame.
99:
100:
101: File: gdb Node: Backtrace, Prev: Frames, Up: Stack, Next: Selection
102:
103: Backtraces
104: ==========
105:
106: A backtrace is a summary of how the program got where it is. It shows one
107: line per frame, for many frames, starting with the currently executing
108: frame (frame zero), followed by its caller (frame one), and on up the
109: stack.
110:
111: `backtrace'
112: `bt'
113: Print a backtrace of the entire stack: one line per frame for all
114: frames in the stack.
115:
116: You can stop the backtrace at any time by typing the system interrupt
117: character, normally `Control-C'.
118:
119: `backtrace N'
120: `bt N'
121: Similar, but stop after N frames.
122:
123: Each line in a backtrace shows the frame number, the program counter, the
124: function and its arguments, and the source file name and line number (if
125: known). The program counter is omitted if is the beginning of the code for
126: the source line. This is the same as the first of the two lines printed
127: when you select a frame.
128:
129:
130: File: gdb Node: Selection, Prev: Backtrace, Up: Stack, Next: Frame Info
131:
132: Selecting a Frame
133: =================
134:
135: Most commands for examining the stack and other data in the program work on
136: whichever stack frame is selected at the moment. Here are the commands for
137: selecting a stack frame; all of them finish by printing a brief description
138: of the stack frame just selected.
139:
140: `frame N'
141: Select frame number N. Recall that frame zero is the innermost
142: (currently executing) frame, frame one is the frame that called the
143: innermost one, and so on. The highest-numbered frame is `main''s
144: frame.
145:
146: `frame ADDR'
147: Select the frame at address ADDR. This is useful mainly if the
148: chaining of stack frames has been damaged by a bug, making it
149: impossible for GDB to assign numbers properly to all frames. In
150: addition, this can be useful when the program has multiple stacks and
151: options between them.
152:
153: `up N'
154: Select the frame N frames up from the frame previously selected.
155: For positive numbers N, this advances toward the outermost
156: frame, to higher frame numbers, to frames that have existed longer.
157: N defaults to one.
158:
159: `down N'
160: Select the frame N frames down from the frame previously
161: selected. For positive numbers N, this advances toward the
162: innermost frame, to lower frame numbers, to frames that were created
163: more recently. N defaults to one.
164:
165: All of these commands end by printing some information on the frame that
166: has been selected: the frame number, the function name, the arguments, the
167: source file and line number of execution in that frame, and the text of
168: that source line. For example:
169:
170: #3 main (argc=3, argv=??, env=??) at main.c, line 67
171: 67 read_input_file (argv[i]);
172:
173: After such a printout, the `list' command with no arguments will print
174: ten lines centered on the point of execution in the frame. *Note List::.
175:
176:
177: File: gdb Node: Frame Info, Prev: Selection, Up: Stack
178:
179: Information on a Frame
180: ======================
181:
182: There are several other commands to print information about the selected
183: stack frame.
184:
185: `frame'
186: This command prints a brief description of the selected stack frame.
187: It can be abbreviated `f'. With an argument, this command is
188: used to select a stack frame; with no argument, it does not change
189: which frame is selected, but still prints the same information.
190:
191: `info frame'
192: This command prints a verbose description of the selected stack frame,
193: including the address of the frame, the addresses of the next frame in
194: (called by this frame) and the next frame out (caller of this frame),
195: the address of the frame's arguments, the program counter saved in it
196: (the address of execution in the caller frame), and which registers
197: were saved in the frame. The verbose description is useful when
198: something has gone wrong that has made the stack format fail to fit
199: the usual conventions.
200:
201: `info frame ADDR'
202: Print a verbose description of the frame at address ADDR,
203: without selecting that frame. The selected frame remains unchanged by
204: this command.
205:
206: `info args'
207: Print the arguments of the selected frame, each on a separate line.
208:
209: `info locals'
210: Print the local variables of the selected frame, each on a separate
211: line. These are all variables declared static or automatic within all
212: program blocks that execution in this frame is currently inside of.
213:
214:
215: File: gdb Node: Source, Prev: Stack, Up: Top, Next: Data
216:
217: Examining Source Files
218: **********************
219:
220: GDB knows which source files your program was compiled from, and
221: can print parts of their text. When your program stops, GDB
222: spontaneously prints the line it stopped in. Likewise, when you
223: select a stack frame (*Note Selection::), GDB prints the line
224: which execution in that frame has stopped in. You can also
225: print parts of source files by explicit command.
226:
227: * Menu:
228:
229: * List:: Using the `list' command to print source files.
230: * Search:: Commands for searching source files.
231: * Source Path:: Specifying the directories to search for source files.
232:
233:
234: File: gdb Node: List, Prev: Source, Up: Source, Next: Search
235:
236: Printing Source Lines
237: =====================
238:
239: To print lines from a source file, use the `list' command
240: (abbreviated `l'). There are several ways to specify what part
241: of the file you want to print.
242:
243: Here are the forms of `list' command most commonly used:
244:
245: `list LINENUM'
246: Print ten lines centered around line number LINENUM in the
247: current source file.
248:
249: `list FUNCTION'
250: Print ten lines centered around the beginning of function
251: FUNCTION.
252:
253: `list'
254: Print ten more lines. If the last lines printed were printed with a
255: `list' command, this prints ten lines following the last lines
256: printed; however, if the last line printed was a solitary line printed
257: as part of displaying a stack frame (*Note Stack::), this prints ten
258: lines centered around that line.
259:
260: `list -'
261: Print ten lines just before the lines last printed.
262:
263: Repeating a `list' command with RET discards the argument,
264: so it is equivalent to typing just `list'. This is more useful
265: than listing the same lines again. An exception is made for an
266: argument of `-'; that argument is preserved in repetition so that
267: each repetition moves up in the file.
268:
269: In general, the `list' command expects you to supply zero, one or two
270: "linespecs". Linespecs specify source lines; there are several ways
271: of writing them but the effect is always to specify some source line.
272: Here is a complete description of the possible arguments for `list':
273:
274: `list LINESPEC'
275: Print ten lines centered around the line specified by LINESPEC.
276:
277: `list FIRST,LAST'
278: Print lines from FIRST to LAST. Both arguments are
279: linespecs.
280:
281: `list ,LAST'
282: Print ten lines ending with LAST.
283:
284: `list FIRST,'
285: Print ten lines starting with FIRST.
286:
287: `list +'
288: Print ten lines just after the lines last printed.
289:
290: `list -'
291: Print ten lines just before the lines last printed.
292:
293: `list'
294: As described in the preceding table.
295:
296: Here are the ways of specifying a single source line---all the
297: kinds of linespec.
298:
299: LINENUM
300: Specifies line LINENUM of the current source file.
301: When a `list' command has two linespecs, this refers to
302: the same source file as the first linespec.
303:
304: +OFFSET
305: Specifies the line OFFSET lines after the last line printed.
306: When used as the second linespec in a `list' command that has
307: two, this specifies the line OFFSET lines down from the
308: first linespec.
309:
310: -OFFSET
311: Specifies the line OFFSET lines before the last line printed.
312:
313: FILENAME:LINENUM
314: Specifies line LINENUM in the source file FILENAME.
315:
316: FUNCTION
317: Specifies the line of the open-brace that begins the body of the
318: function FUNCTION.
319:
320: FILENAME:FUNCTION
321: Specifies the line of the open-brace that begins the body of the
322: function FUNCTION in the file FILENAME. The file name is
323: needed with a function name only for disambiguation of identically
324: named functions in different source files.
325:
326: *ADDRESS
327: Specifies the line containing the program address ADDRESS.
328: ADDRESS may be any expression.
329:
330: One other command is used to map source lines to program addresses.
331:
332: `info line LINENUM'
333: Print the starting and ending addresses of the compiled code for
334: source line LINENUM.
335:
336: The default examine address for the `x' command is changed to the
337: starting address of the line, so that `x/i' is sufficient to
338: begin examining the machine code (*Note Memory::). Also, this address
339: is saved as the value of the convenience variable `$_'
340: (*Note Convenience Vars::).
341:
342:
343: File: gdb Node: Search, Prev: List, Up: Source, Next: Source Path
344:
345: Searching Source Files
346: ======================
347:
348: There are two commands for searching through the current source file for a
349: regular expression.
350:
351: The command `forward-search REGEXP' checks each line, starting
352: with the one following the last line listed, for a match for REGEXP.
353: It lists the line that is found. You can abbreviate the command name
354: as `fo'.
355:
356: The command `reverse-search REGEXP' checks each line, starting
357: with the one before the last line listed and going backward, for a match
358: for REGEXP. It lists the line that is found. You can abbreviate
359: this command with as little as `rev'.
360:
361:
362: File: gdb Node: Source Path, Prev: Search, Up: Source
363:
364: Specifying Source Directories
365: =============================
366:
367: Executable programs do not record the directories of the source files they
368: were compiled from, just the names. GDB remembers a list of directories to
369: search for source files; this is called the "source path". Each time
370: GDB wants a source file, it tries all the directories in the list, in the
371: order they are present in the list, until it finds a file with the desired
372: name.
373:
374: When you start GDB, its source path contains just the current working
375: directory. To add other directories, use the `directory' command.
376: Note that the search path for executable files and the working directory
377: are not used for finding source files.
378:
379: `directory DIRNAME'
380: Add directory DIRNAME to the end of the source path.
381:
382: `directory'
383: Reset the source path to just the current working directory of GDB.
384: This requires confirmation.
385:
386: `directory' with no argument can cause source files previously
387: found by GDB to be found in a different directory. To make this work
388: correctly, this command also clears out the tables GDB maintains
389: about the source files it has already found.
390:
391: `info directories'
392: Print the source path: show which directories it contains.
393:
394: Because the `directory' command adds to the end of the source path,
395: it does not affect any file that GDB has already found. If the source
396: path contains directories that you do not want, and these directories
397: contain misleading files with names matching your source files, the
398: way to correct the situation is as follows:
399:
400: 1. Choose the directory you want at the beginning of the source path.
401: Use the `cd' command to make that the current working directory.
402:
403: 2. Use `directory' with no argument to reset the source path to just
404: that directory.
405:
406: 3. Use `directory' with suitable arguments to add any other
407: directories you want in the source path.
408:
409:
410: File: gdb Node: Data, Prev: Source, Up: Top, Next: Symbols
411:
412: Examining Data
413: **************
414:
415: The usual way of examining data in your program is with the `print'
416: command (abbreviated `p'). It evaluates and prints the value of any
417: valid expression of the language the program is written in (for now, C).
418: You type
419:
420: print EXP
421:
422: where EXP is any valid expression, and the value of EXP
423: is printed in a format appropriate to its data type.
424:
425: A more low-level way of examining data is with the `x' command.
426: It examines data in memory at a specified address and prints it in a
427: specified format.
428:
429: * Menu:
430:
431: * Expressions:: Expressions that can be computed and printed.
432: * Variables:: Using your program's variables in expressions.
433: * Assignment:: Setting your program's variables.
434: * Arrays:: Examining part of memory as an array.
435: * Formats:: Specifying formats for printing values.
436: * Memory:: Examining memory explicitly.
437: * Auto Display:: Printing certain expressions whenever program stops.
438: * Value History:: Referring to values previously printed.
439: * Convenience Vars:: Giving names to values for future reference.
440: * Registers:: Referring to and storing in machine registers.
441:
442:
443: File: gdb Node: Expressions, Prev: Data, Up: Data, Next: Variables
444:
445: Expressions
446: ===========
447:
448: Many different GDB commands accept an expression and compute its value.
449: Any kind of constant, variable or operator defined by the programming
450: language you are using is legal in an expression in GDB. This includes
451: conditional expressions, function calls, casts and string constants.
452:
453: Casts are supported in all languages, not just in C, because it is so
454: useful to cast a number into a pointer so as to examine a structure
455: at that address in memory.
456:
457: GDB supports three kinds of operator in addition to those of programming
458: languages:
459:
460: `@'
461: `@' is a binary operator for treating parts of memory as arrays.
462: *Note Arrays::, for more information.
463:
464: `::'
465: `::' allows you to specify a variable in terms of the file or
466: function it is defined in. *Note Variables::.
467:
468: `{TYPE} ADDR'
469: Refers to an object of type TYPE stored at address ADDR in memory.
470: ADDR may be any expression whose value is an integer or pointer (but
471: parentheses are required around nonunary operators, just as in a
472: cast). This construct is allowed regardless of what kind of data is
473: officially supposed to reside at ADDR.
474:
475:
476: File: gdb Node: Variables, Prev: Expressions, Up: Data, Next: Arrays
477:
478: Program Variables
479: =================
480:
481: The most common kind of expression to use is the name of a variable
482: in your program.
483:
484: Variables in expressions are understood in the selected stack frame
485: (*Note Selection::); they must either be global (or static) or be visible
486: according to the scope rules of the programming language from the point of
487: execution in that frame. This means that in the function
488:
489: foo (a)
490: int a;
491: {
492: bar (a);
493: {
494: int b = test ();
495: bar (b);
496: }
497: }
498:
499: the variable `a' is usable whenever the program is executing
500: within the function `foo', but the variable `b' is visible
501: only while the program is executing inside the block in which `b'
502: is declared.
503:
504:
505: File: gdb Node: Arrays, Prev: Variables, Up: Data, Next: Formats
506:
507: Artificial Arrays
508: =================
509:
510: It is often useful to print out several successive objects of the
511: same type in memory; a section of an array, or an array of
512: dynamically determined size for which only a pointer exists in the
513: program.
514:
515: This can be done by constructing an "artificial array" with the
516: binary operator `@'. The left operand of `@' should be
517: the first element of the desired array, as an individual object.
518: The right operand should be the length of the array. The result is
519: an array value whose elements are all of the type of the left argument.
520: The first element is actually the left argument; the second element
521: comes from bytes of memory immediately following those that hold the
522: first element, and so on. Here is an example. If a program says
523:
524: int *array = (int *) malloc (len * sizeof (int));
525:
526: you can print the contents of `array' with
527:
528: p *array@len
529:
530: The left operand of `@' must reside in memory. Array values made
531: with `@' in this way behave just like other arrays in terms of
532: subscripting, and are coerced to pointers when used in expressions.
533: (It would probably appear in an expression via the value history,
534: after you had printed it out.)
535:
536:
537: File: gdb Node: Formats, Prev: Arrays, Up: Data, Next: Memory
538:
539: Formats
540: =======
541:
542: GDB normally prints all values according to their data types. Sometimes
543: this is not what you want. For example, you might want to print a number
544: in hex, or a pointer in decimal. Or you might want to view data in memory
545: at a certain address as a character string or an instruction. These things
546: can be done with "output formats".
547:
548: The simplest use of output formats is to say how to print a value
549: already computed. This is done by starting the arguments of the
550: `print' command with a slash and a format letter. The format
551: letters supported are:
552:
553: `x'
554: Regard the bits of the value as an integer, and print the integer in
555: hexadecimal.
556:
557: `d'
558: Print as integer in signed decimal.
559:
560: `u'
561: Print as integer in unsigned decimal.
562:
563: `o'
564: Print as integer in octal.
565:
566: `a'
567: Print as an address, both absolute in hex and then relative
568: to a symbol defined as an address below it.
569:
570: `c'
571: Regard as an integer and print it as a character constant.
572:
573: `f'
574: Regard the bits of the value as a floating point number and print
575: using typical floating point syntax.
576:
577: For example, to print the program counter in hex (*Note Registers::), type
578:
579: p/x $pc
580:
581: Note that no space is required before the slash; this is because command
582: names in GDB cannot contain a slash.
583:
584: To reprint the last value in the value history with a different format,
585: you can use the `print' command with just a format and no
586: expression. For example, `p/x' reprints the last value in hex.
587:
588:
589: File: gdb Node: Memory, Prev: Formats, Up: Data, Next: Auto Display
590:
591: Examining Memory
592: ----------------
593:
594: The command `x' (for `examine') can be used to examine memory under
595: explicit control of formats, without reference to the program's data types.
596:
597: `x' is followed by a slash and an output format specification,
598: followed by an expression for an address. The expression need not have
599: a pointer value (though it may); it is used as an integer, as the
600: address of a byte of memory.
601:
602: The output format in this case specifies both how big a unit of memory
603: to examine and how to print the contents of that unit. It is done
604: with one or two of the following letters:
605:
606: These letters specify just the size of unit to examine:
607:
608: `b'
609: Examine individual bytes.
610:
611: `h'
612: Examine halfwords (two bytes each).
613:
614: `w'
615: Examine words (four bytes each).
616:
617: Many assemblers and cpu designers still use `word' for a 16-bit quantity,
618: as a holdover from specific predecessor machines of the 1970's that really
619: did use two-byte words. But more generally the term `word' has always
620: referred to the size of quantity that a machine normally operates on and
621: stores in its registers. This is 32 bits for all the machines that GNU
622: runs on.
623:
624: `g'
625: Examine giant words (8 bytes).
626:
627: These letters specify just the way to print the contents:
628:
629: `x'
630: Print as integers in unsigned hexadecimal.
631:
632: `d'
633: Print as integers in signed decimal.
634:
635: `u'
636: Print as integers in unsigned decimal.
637:
638: `o'
639: Print as integers in unsigned octal.
640:
641: `a'
642: Print as an address, both absolute in hex and then relative
643: to a symbol defined as an address below it.
644:
645: `c'
646: Print as character constants.
647:
648: `f'
649: Print as floating point. This works only with sizes `w' and
650: `g'.
651:
652: `s'
653: Print a null-terminated string of characters. The specified unit size
654: is ignored; instead, the unit is however many bytes it takes to reach
655: a null character (including the null character).
656:
657: `i'
658: Print a machine instruction in assembler syntax (or nearly). The
659: specified unit size is ignored; the number of bytes in an instruction
660: varies depending on the type of machine, the opcode and the addressing
661: modes used.
662:
663: If either the manner of printing or the size of unit fails to be specified,
664: the default is to use the same one that was used last. If you don't want
665: to use any letters after the slash, you can omit the slash as well.
666:
667: You can also omit the address to examine. Then the address used is
668: just after the last unit examined. This is why string and instruction
669: formats actually compute a unit-size based on the data: so that the
670: next string or instruction examined will start in the right place.
671: The `print' command sometimes sets the default address for
672: the `x' command; when the value printed resides in memory, the
673: default is set to examine the same location. `info line' also
674: sets the default for `x', to the address of the start of the
675: machine code for the specified line and `info breakpoints' sets
676: it to the address of the last breakpoint listed.
677:
678: When you use RET to repeat an `x' command, it does not repeat
679: exactly the same: the address specified previously (if any) is ignored, so
680: that the repeated command examines the successive locations in memory
681: rather than the same ones.
682:
683: You can examine several consecutive units of memory with one command by
684: writing a repeat-count after the slash (before the format letters, if any).
685: The repeat count must be a decimal integer. It has the same effect as
686: repeating the `x' command that many times except that the output may
687: be more compact with several units per line.
688:
689: x/10i $pc
690:
691: Prints ten instructions starting with the one to be executed next in the
692: selected frame. After doing this, you could print another ten following
693: instructions with
694:
695: x/10
696:
697: in which the format and address are allowed to default.
698:
699: The addresses and contents printed by the `x' command are not put in
700: the value history because there is often too much of them and they would
701: get in the way. Instead, GDB makes these values available for subsequent
702: use in expressions as values of the convenience variables `$_' and
703: `$__'.
704:
705: After an `x' command, the last address examined is available for use
706: in expressions in the convenience variable `$_'. The contents of that
707: address, as examined, are available in the convenience variable `$__'.
708:
709: If the `x' command has a repeat count, the address and contents saved
710: are from the last memory unit printed; this is not the same as the last
711: address printed if several units were printed on the last line of output.
712:
713:
714: File: gdb Node: Auto Display, Prev: Memory, Up: Data, Next: Value History
715:
716: Automatic Display
717: =================
718:
719: If you find that you want to print the value of an expression frequently
720: (to see how it changes), you might want to add it to the "automatic
721: display list" so that GDB will print its value each time the program stops.
722: Each expression added to the list is given a number to identify it;
723: to remove an expression from the list, you specify that number.
724: The automatic display looks like this:
725:
726: 2: foo = 38
727: 3: bar[5] = (struct hack *) 0x3804
728:
729: showing item numbers, expressions and their current values.
730:
731: `display EXP'
732: Add the expression EXP to the list of expressions to display
733: each time the program stops.
734:
735: `display/FMT EXP'
736: For FMT specifying only a display format and not a size or
737: count, add the expression EXP to the auto-display list but
738: arranges to display it each time in the specified format FMT.
739:
740: `display/FMT ADDR'
741: For FMT `i' or `s', or including a unit-size or a
742: number of units, add the expression ADDR as a memory address to
743: be examined each time the program stops. Examining means in effect
744: doing `x/FMT ADDR'. *Note Memory::.
745:
746: `undisplay N'
747: Remove item number N from the list of expressions to display.
748:
749: `display'
750: Display the current values of the expressions on the list, just as is
751: done when the program stops.
752:
753: `info display'
754: Print the list of expressions to display automatically, each one
755: with its item number, but without showing the values.
756:
757:
758: File: gdb Node: Value History, Prev: Auto Display, Up: Data, Next: Convenience Vars
759:
760: Value History
761: =============
762:
763: Every value printed by the `print' command is saved for the entire
764: session in GDB's "value history" so that you can refer to it in
765: other expressions.
766:
767: The values printed are given "history numbers" for you to refer to them
768: by. These are successive integers starting with 1. `print' shows you
769: the history number assigned to a value by printing `$N = '
770: before the value; here N is the history number.
771:
772: To refer to any previous value, use `$' followed by the value's
773: history number. The output printed by `print' is designed to remind
774: you of this. Just `$' refers to the most recent value in the history,
775: and `$$' refers to the value before that.
776:
777: For example, suppose you have just printed a pointer to a structure and
778: want to see the contents of the structure. It suffices to type
779:
780: p *$
781:
782: If you have a chain of structures where the component `next' points
783: to the next one, you can print the contents of the next one with
784:
785: p *$.next
786:
787: It might be useful to repeat this command many times by typing RET.
788:
789: Note that the history records values, not expressions. If the value of
790: `x' is 4 and you type
791:
792: print x
793: set x=5
794:
795: then the value recorded in the value history by the `print' command
796: remains 4 even though `x''s value has changed.
797:
798: `info history'
799: Print the last ten values in the value history, with their item
800: numbers. This is like `p $$9' repeated ten times, except that
801: `info history' does not change the history.
802:
803: `info history N'
804: Print ten history values centered on history item number N.
805:
806:
807: File: gdb Node: Convenience Vars, Prev: Value History, Up: Data, Next: Registers
808:
809: Convenience Variables
810: =====================
811:
812: GDB provides "convenience variables" that you can use within GDB to
813: hold on to a value and refer to it later. These variables exist entirely
814: within GDB; they are not part of your program, and setting a convenience
815: variable has no effect on further execution of your program. That's why
816: you can use them freely.
817:
818: Convenience variables have names starting with `$'. Any name starting
819: with `$' can be used for a convenience variable, unless it is one of
820: the predefined set of register names (*Note Registers::).
821:
822: You can save a value in a convenience variable with an assignment
823: expression, just as you would set a variable in your program. Example:
824:
825: set $foo = *object_ptr
826:
827: would save in `$foo' the value contained in the object pointed to by
828: `object_ptr'.
829:
830: Using a convenience variable for the first time creates it; but its value
831: is `void' until you assign a new value. You can alter the value with
832: another assignment at any time.
833:
834: Convenience variables have no fixed types. You can assign a convenience
835: variable any type of value, even if it already has a value of a different
836: type. The convenience variable as an expression has whatever type its
837: current value has.
838:
839: `info convenience'
840: Print a list of convenience variables used so far, and their values.
841: Abbreviated `i con'.
842:
843: One of the ways to use a convenience variable is as a counter to be
844: incremented or a pointer to be advanced. For example:
845:
846: set $i = 0
847: print bar[$i++]->contents
848: ...repeat that command by typing RET.
849:
850: Some convenience variables are created automatically by GDB and given
851: values likely to be useful.
852:
853: `$_'
854: The variable `$_' is automatically set by the `x' command to
855: the last address examined (*Note Memory::). Other commands which
856: provide a default address for `x' to examine also set `$_'
857: to that address; these commands include `info line' and `info
858: breakpoint'.
859:
860: `$__'
861: The variable `$__' is automatically set by the `x' command
862: to the value found in the last address examined.
863:
864:
865: File: gdb Node: Registers, Prev: Convenience Vars, Up: Data
866:
867: Registers
868: =========
869:
870: Machine register contents can be referred to in expressions as variables
871: with names starting with `$'. The names of registers are different
872: for each machine; use `info registers' to see the names used on your
873: machine. The names `$pc' and `$sp' are used on all machines for
874: the program counter register and the stack pointer. Often `$fp' is
875: used for a register that contains a pointer to the current stack frame.
876:
877: GDB always considers the contents of an ordinary register as an integer
878: when the register is examined in this way. Programs can store floating
879: point values in registers also, but there is currently no GDB command
880: to examine a specified register in floating point. (However, if the
881: variable in your program which is stored in the register is a floating
882: point variable, you can see the floating point value by examining
883: the variable.)
884:
885: Some machines have special floating point registers. GDB considers these
886: registers' values as floating point when you examine them explicitly.
887:
888: Some registers have distinct "raw" and "virtual" data formats. This
889: means that the data format in which the register contents are saved by the
890: operating system is not the same one that your program normally sees. For
891: example, the registers of the 68881 floating point coprocessor are always
892: saved in "extended" format, but all C programs expect to work with
893: "double" format. In such cases, GDB normally works with the virtual
894: format only (the format that makes sense for your program), but the
895: `info registers' command prints the data in both formats.
896:
897: Register values are relative to the selected stack frame
898: (*Note Selection::). This means that you get the value that the register
899: would contain if all stack frames farther in were exited and their saved
900: registers restored. In order to see the real contents of all registers,
901: you must select the innermost frame (with `frame 0').
902:
903: Some registers are never saved (typically those numbered zero or one)
904: because they are used for returning function values; for these registers,
905: relativization makes no difference.
906:
907: `info registers'
908: Print the names and relativized values of all registers.
909:
910: `info registers REGNAME'
911: Print the relativized value of register REGNAME. REGNAME
912: may be any register name valid on the machine you are using, with
913: or without the initial `$'.
914:
915:
916: Examples
917: --------
918:
919: You could print the program counter in hex with
920:
921: p/x $pc
922:
923: or print the instruction to be executed next with
924:
925: x/i $pc
926:
927: or add four to the stack pointer with
928:
929: set $sp += 4
930:
931: The last is a way of removing one word from the stack, on machines where
932: stacks grow downward in memory (most machines, nowadays). This assumes
933: that the innermost stack frame is selected. Setting `$sp' is
934: not allowed when other stack frames are selected.
935:
936:
937: File: gdb Node: Symbols, Prev: Data, Up: Top, Next: Altering
938:
939: Examining the Symbol Table
940: **************************
941:
942: The commands described in this section allow you to make inquiries for
943: information about the symbols (names of variables, functions and types)
944: defined in your program. This information is found by GDB in the symbol
945: table loaded by the `symbol-file' command; it is inherent in the text
946: of your program and does not change as the program executes.
947:
948: `whatis EXP'
949: Print the data type of expression EXP. EXP is not
950: actually evaluated, and any side-effecting operations (such as
951: assignments or function calls) inside it do not take place.
952:
953: `whatis'
954: Print the data type of `$', the last value in the value history.
955:
956: `info address SYMBOL'
957: Describe where the data for SYMBOL is stored. For register
958: variables, this says which register. For other automatic variables,
959: this prints the stack-frame offset at which the variable is always
960: stored. Note the contrast with `print &SYMBOL', which does
961: not work at all for register variables and for automatic variables
962: prints the exact address of the current instantiation of the variable.
963:
964: `ptype TYPENAME'
965: Print a description of data type TYPENAME. TYPENAME may be the name
966: of a type, or for C code it may have the form `struct STRUCT-TAG',
967: `union UNION-TAG' or `enum ENUM-TAG'.
968:
969: `info sources'
970: Print the names of all source files in the program for which there
971: is debugging information.
972:
973: `info functions'
974: Print the names and data types of all defined functions.
975:
976: `info functions REGEXP'
977: Print the names and data types of all defined functions
978: whose names contain a match for regular expression REGEXP.
979: Thus, `info fun step' finds all functions whose names
980: include `step'; `info fun ^step' finds those whose names
981: start with `step'.
982:
983: `info variables'
984: Print the names and data types of all variables that are declared
985: outside of functions.
986:
987: `info variables REGEXP'
988: Print the names and data types of all variables, declared outside of
989: functions, whose names contain a match for regular expression
990: REGEXP.
991:
992: `info types'
993: Print all data types that are defined in the program.
994:
995: `info types REGEXP'
996: Print all data types that are defined in the program whose names
997: contain a match for regular expression REGEXP.
998:
999: `printsyms FILENAME'
1000: Write a complete dump of the debugger's symbol data into the
1001: file FILENAME.
1002:
1003:
1004: File: gdb Node: Altering, Prev: Symbols, Up: Top, Next: Sequences
1005:
1006: Altering Execution
1007: ******************
1008:
1009: There are several ways to alter the execution of your program with GDB
1010: commands.
1011:
1012: * Menu:
1013:
1014: * Assignment:: Altering variable values or memory contents.
1015: * Jumping:: Altering control flow.
1016: * Signaling:: Making signals happen in the program.
1017: * Returning:: Making a function return prematurely.
1018:
1019:
1020: File: gdb Node: Assignment, Prev: Altering, Up: Altering, Next: Jumping
1021:
1022: Assignment to Variables
1023: =======================
1024:
1025: To alter the value of a variable, evaluate an assignment expression.
1026: For example,
1027:
1028: print x=4
1029:
1030: would store the value 4 into the variable `x', and then print
1031: the value of the assignment expression (which is 4).
1032:
1033: If you are not interested in seeing the value of the assignment, use the
1034: `set' command instead of the `print' command. `set' is
1035: really the same as `print' except that the expression's value is not
1036: printed and is not put in the value history (*Note Value History::). The
1037: expression is evaluated only for side effects.
1038:
1039: GDB allows more implicit conversions in assignments than C does; you can
1040: freely store an integer value into a pointer variable or vice versa, and
1041: any structure can be converted to any other structure that is the same
1042: length or shorter.
1043:
1044: In C, all the other assignment operators such as `+=' and `++'
1045: are supported as well.
1046:
1047: To store into arbitrary places in memory, use the `{...}'
1048: construct to generate a value of specified type at a specified address
1049: (*Note Expressions::). For example,
1050:
1051: set {int}0x83040 = 4
1052:
1053:
1054: File: gdb Node: Jumping, Prev: Assignment, Up: Altering, Next: Signaling
1055:
1056: Continuing at a Different Address
1057: =================================
1058:
1059: `jump LINENUM'
1060: Resume execution at line number LINENUM. Execution may stop
1061: immediately if there is a breakpoint there.
1062:
1063: The `jump' command does not change the current stack frame, or
1064: the stack pointer, or the contents of any memory location or any
1065: register other than the program counter. If line LINENUM is in
1066: a different function from the one currently executing, the results may
1067: be wild if the two functions expect different patterns of arguments or
1068: of local variables. For his reason, the `jump' command requests
1069: confirmation if the specified line is not in the function currently
1070: executing. However, even wild results are predictable based on
1071: changing the program counter.
1072:
1073: `jump *ADDRESS'
1074: Resume execution at the instruction at address ADDRESS.
1075:
1076: A similar effect can be obtained by storing a new value into the register
1077: `$pc', but not exactly the same.
1078:
1079: set $pc = 0x485
1080:
1081: specifies the address at which execution will resume, but does not resume
1082: execution. That does not happen until you use the `cont' command or a
1083: stepping command (*Note Stepping::).
1084:
1085:
1086: File: gdb Node: Signaling, Prev: Jumping, Up: Altering, Next: Returning
1087:
1088: Giving the Program a Signal
1089: ===========================
1090:
1091: `signal SIGNALNUM'
1092: Resume execution where the program stopped, but give it immediately
1093: the signal number SIGNALNUM.
1094:
1095: Alternatively, if SIGNALNUM is zero, continue execution and give
1096: no signal. This may be useful when the program has received a signal
1097: and the `cont' command would allow the program to see that
1098: signal.
1099:
1100:
1101: File: gdb Node: Returning, Prev: Signaling, Up: Altering
1102:
1103: Returning from a Function
1104: =========================
1105:
1106: You can make any function call return immediately, using the `return'
1107: command.
1108:
1109: First select the stack frame that you wish to return from
1110: (*Note Selection::). Then type the `return' command. If you wish to
1111: specify the value to be returned, give that as an argument.
1112:
1113: This pops the selected stack frame (and any other frames inside of it),
1114: leaving its caller as the innermost remaining frame. That frame becomes
1115: selected. The specified value is stored in the registers used for
1116: returning values of functions.
1117:
1118: The `return' command does not resume execution; it leaves the program
1119: stopped in the state that would exist if the function had just returned.
1120: Contrast this with the `finish' command (*Note Stepping::), which
1121: resumes execution until the selected stack frame returns naturally.
1122:
1123:
1124: File: gdb Node: Sequences, Prev: Altering, Up: Top, Next: Emacs
1125:
1126: Canned Sequences of Commands
1127: ****************************
1128:
1129: GDB provides two ways to store sequences of commands for execution as a
1130: unit: user-defined commands and command files.
1131:
1132: * Menu:
1133:
1134: * Define:: User-defined commands.
1135: * Command Files:: Command files.
1136: * Output:: Controlled output commands useful in
1137: user-defined commands and command files.
1138:
1139:
1140: File: gdb Node: Define, Prev: Sequences, Up: Sequences, Next: Command Files
1141:
1142: User-Defined Commands
1143: =====================
1144:
1145: A "user-defined command" is a sequence of GDB commands to which you
1146: assign a new name as a command. This is done with the `define'
1147: command.
1148:
1149: `define COMMANDNAME'
1150: Define a command named COMMANDNAME. If there is already a command
1151: by that name, you are asked to confirm that you want to redefine it.
1152:
1153: The definition of the command is made up of other GDB command lines,
1154: which are given following the `define' command. The end of these
1155: commands is marked by a line containing `end'.
1156:
1157: `document COMMANDNAME'
1158: Give documentation to the user-defined command COMMANDNAME. The
1159: command COMMANDNAME must already be defined. This command reads
1160: lines of documentation just as `define' reads the lines of the
1161: command definition. After the `document' command is finished,
1162: `help' on command COMMANDNAME will print the documentation
1163: you have specified.
1164:
1165: You may use the `document' command again to change the
1166: documentation of a command. Redefining the command with `define'
1167: does not change the documentation.
1168:
1169: User-defined commands do not take arguments. When they are executed, the
1170: commands of the definition are not printed. An error in any command
1171: stops execution of the user-defined command.
1172:
1173: Commands that would ask for confirmation if used interactively proceed
1174: without asking when used inside a user-defined command. Many GDB commands
1175: that normally print messages to say what they are doing omit the messages
1176: when used in user-defined command.
1177:
1178:
1179: File: gdb Node: Command Files, Prev: Define, Up: Sequences, Next: Output
1180:
1181: Command Files
1182: =============
1183:
1184: A command file for GDB is a file of lines that are GDB commands. Comments
1185: (lines starting with `#') may also be included. An empty line in a
1186: command file does nothing; it does not mean to repeat the last command, as
1187: it would from the terminal.
1188:
1189: When GDB starts, it automatically executes its "init files", command
1190: files named `.gdbinit'. GDB reads the init file (if any) in your home
1191: directory and then the init file (if any) in the current working
1192: directory. (The init files are not executed if the `-nx' option
1193: is given.) You can also request the execution of a command file with the
1194: `source' command:
1195:
1196: `source FILENAME'
1197: Execute the command file FILENAME.
1198:
1199: The lines in a command file are executed sequentially. They are not
1200: printed as they are executed. An error in any command terminates execution
1201: of the command file.
1202:
1203: Commands that would ask for confirmation if used interactively proceed
1204: without asking when used in a command file. Many GDB commands that
1205: normally print messages to say what they are doing omit the messages
1206: when used in a command file.
1207:
1208:
1209: File: gdb Node: Output, Prev: Command Files, Up: Sequences
1210:
1211: Commands for Controlled Output
1212: ==============================
1213:
1214: During the execution of a command file or a user-defined command, the only
1215: output that appears is what is explicitly printed by the commands of the
1216: definition. This section describes three commands useful for generating
1217: exactly the output you want.
1218:
1219: `echo TEXT'
1220: Print TEXT. Nonprinting characters can be included in
1221: TEXT using C escape sequences, such as `\n' to print a
1222: newline. No newline will be printed unless you specify one.
1223:
1224: A backslash at the end of TEXT is ignored. It is useful for
1225: outputting a string ending in spaces, since trailing spaces are
1226: trimmed from all arguments. A backslash at the beginning preserves
1227: leading spaces in the same way, because `\ ' as an escape
1228: sequence stands for a space. Thus, to print ` and foo = ', do
1229:
1230: echo \ and foo = \
1231:
1232: `output EXPRESSION'
1233: Print the value of EXPRESSION and nothing but that value: no
1234: newlines, no `$NN = '. The value is not entered in the
1235: value history either.
1236:
1237: `output/FMT EXPRESSION'
1238: Print the value of EXPRESSION in format FMT.
1239: *Note Formats::, for more information.
1240:
1241: `printf STRING, EXPRESSIONS...'
1242: Print the values of the EXPRESSIONS under the control of
1243: STRING. The EXPRESSIONS are separated by commas and may
1244: be either numbers or pointers. Their values are printed as specified
1245: by STRING, exactly as if the program were to execute
1246:
1247: printf (STRING, EXPRESSIONS...);
1248:
1249: For example, you can print two values in hex like this:
1250:
1251: printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
1252:
1253: The only backslash-escape sequences that you can use in the string are
1254: the simple ones that consist of backslash followed by a letter.
1255:
1256:
1257: File: gdb Node: Emacs, Prev: Sequences, Up: Top, Next: Remote
1258:
1259: Using GDB under GNU Emacs
1260: *************************
1261:
1262: A special interface allows you to use GNU Emacs to view (and
1263: edit) the source files for the program you are debugging with
1264: GDB.
1265:
1266: To use this interface, use the command `M-x gdb' in Emacs.
1267: Give the executable file you want to debug as an argument. This
1268: command starts a GDB process as a subprocess of Emacs, with input
1269: and output through a newly created Emacs buffer.
1270:
1271: Using this GDB process is just like using GDB normally except for two things:
1272:
1273: * All "terminal" input and output goes through the Emacs buffer. This
1274: applies both to GDB commands and their output, and to the input and
1275: output done by the program you are debugging.
1276:
1277: This is useful because it means that you can copy the text of previous
1278: commands and input them again; you can even use parts of the output
1279: in this way.
1280:
1281: All the facilities of Emacs's Shell mode are available for this purpose.
1282:
1283: * GDB displays source code through Emacs. Each time GDB displays a
1284: stack frame, Emacs automatically finds the source file for that frame
1285: and puts an arrow (`=>') at the left margin of the current line.
1286:
1287: Explicit GDB `list' or search commands still produce output as
1288: usual, but you probably will have no reason to use them.
1289:
1290: In the GDB I/O buffer, you can use these special Emacs commands:
1291:
1292: `M-s'
1293: Execute to another source line, like the GDB `step' command.
1294:
1295: `M-n'
1296: Execute to next source line in this function, skipping all function
1297: calls, like the GDB `next' command.
1298:
1299: `M-i'
1300: Execute one instruction, like the GDB `stepi' command.
1301:
1302: `M-u'
1303: Move up one stack frame (and display that frame's source file in
1304: Emacs), like the GDB `up' command.
1305:
1306: `M-d'
1307: Move down one stack frame (and display that frame's source file in
1308: Emacs), like the GDB `down' command. (This means that you cannot
1309: delete words in the usual fashion in the GDB buffer; I am guessing you
1310: won't often want to do that.)
1311:
1312: `C-c C-f'
1313: Execute until exit from the selected stack frame, like the GDB
1314: `finish' command.
1315:
1316: In any source file, the Emacs command `C-x SPC' (`gdb-break')
1317: tells GDB to set a breakpoint on the source line point is on.
1318:
1319: The source files displayed in Emacs are in ordinary Emacs buffers
1320: which are visiting the source files in the usual way. You can edit
1321: the files with these buffers if you wish; but keep in mind that GDB
1322: communicates with Emacs in terms of line numbers. If you add or
1323: delete lines from the text, the line numbers that GDB knows will cease
1324: to correspond properly to the code.
1325:
1326:
1327: File: gdb Node: Remote, Prev: Emacs, Up: Top, Next: Commands
1328:
1329: Remote Kernel Debugging
1330: ***********************
1331:
1332: GDB has a special facility for debugging a remote machine via a serial
1333: connection. This can be used for kernel debugging.
1334:
1335: The program to be debugged on the remote machine needs to contain a
1336: debugging device driver which talks to GDB over the serial line using the
1337: protocol described below. The same version of GDB that is used ordinarily
1338: can be used for this.
1339:
1340: * Menu:
1341:
1342: * Remote Commands:: Commands used to start and finish remote debugging.
1343:
1344: For details of the communication protocol, see the comments in the GDB
1345: source file `remote.c'.
1346:
1347:
1348: File: gdb Node: Remote Commands, Prev: Remote, Up: Remote
1349:
1350: Commands for Remote Debugging
1351: =============================
1352:
1353: To start remote debugging, first run GDB and specify as an executable file
1354: the program that is running in the remote machine. This tells GDB how
1355: to find the program's symbols and the contents of its pure text. Then
1356: establish communication using the `attach' command with a device
1357: name rather than a pid as an argument. For example:
1358:
1359: attach /dev/ttyd
1360:
1361: if the serial line is connected to the device named `/dev/ttyd'. This
1362: will stop the remote machine if it is not already stopped.
1363:
1364: Now you can use all the usual commands to examine and change data and to
1365: step and continue the remote program.
1366:
1367: To resume the remote program and stop debugging it, use the `detach'
1368: command.
1369:
1370:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.