![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gdb+.texinfo CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GNU Debugger] / gdb|
Return to gdb+.texinfo CVS log | Up to [GNU Debugger] / gdb |
1.1 root 1: \input texinfo
2: @setfilename ../info/gdb
3: @settitle GDB+, The GNU Debugger for GNU C++
4: @ifinfo
5: This file documents the GNU debugger GDB+.
6:
7: Copyright (C) 1988 Richard M. Stallman.
8: Modified by Michael Tiemann
9:
10: Permission is granted to make and distribute verbatim copies of
11: this manual provided the copyright notice and this permission notice
12: are preserved on all copies.
13:
14: @ignore
15: Permission is granted to process this file through Tex and print the
16: results, provided the printed document carries copying permission
17: notice identical to this one except for the removal of this paragraph
18: (this paragraph not being relevant to the printed manual).
19:
20: @end ignore
21: Permission is granted to copy and distribute modified versions of this
22: manual under the conditions for verbatim copying, provided also that the
23: sections entitled ``Distribution'' and ``GDB General Public License'' are
24: included exactly as in the original, and provided that the entire resulting
25: derived work is distributed under the terms of a permission notice
26: identical to this one.
27:
28: Permission is granted to copy and distribute translations of this manual
29: into another language, under the above conditions for modified versions,
30: except that the sections entitled ``Distribution'' and ``GDB General Public
31: License'' may be included in a translation approved by the author instead
32: of in the original English.
33: @end ifinfo
34:
35: @setchapternewpage odd
36: @settitle GDB+ Manual
37: @titlepage
38: @sp 6
39: @center @titlefont{GDB+ Manual}
40: @sp 1
41: @center The GNU Source-Level Debugger for GNU C++
42: @sp 4
43: @center Second Edition, GDB+ version 2.5.0
44: @sp 1
45: @center February 1988
46: @sp 5
47: @center Richard M. Stallman
48: @page
49: @vskip 0pt plus 1filll
50: Copyright @copyright{} 1988 Richard M. Stallman.
51: Modified by Michael Tiemann
52:
53: Permission is granted to make and distribute verbatim copies of
54: this manual provided the copyright notice and this permission notice
55: are preserved on all copies.
56:
57: Permission is granted to copy and distribute modified versions of this
58: manual under the conditions for verbatim copying, provided also that the
59: sections entitled ``Distribution'' and ``GDB General Public License'' are
60: included exactly as in the original, and provided that the entire resulting
61: derived work is distributed under the terms of a permission notice
62: identical to this one.
63:
64: Permission is granted to copy and distribute translations of this manual
65: into another language, under the above conditions for modified versions,
66: except that the sections entitled ``Distribution'' and ``GDB General Public
67: License'' may be included in a translation approved by the author instead
68: of in the original English.
69: @end titlepage
70: @page
71:
72: @node Top, Commands,, (DIR)
73: @unnumbered Summary of GDB+
74:
75: The purpose of a debugger such as GDB+ is to allow you to execute another
76: program while examining what is going on inside it. We call the other
77: program ``your program'' or ``the program being debugged''.
78:
79: GDB+ can do four kinds of things (plus other things in support of these):
80:
81: @enumerate
82: @item
83: Start the program, specifying anything that might affect its behavior.
84:
85: @item
86: Make the program stop on specified conditions.
87:
88: @item
89: Examine what has happened, when the program has stopped, so that you
90: can see bugs happen.
91:
92: @item
93: Change things in the program, so you can correct the effects of one bug
94: and go on to learn about another without having to recompile first.
95: @end enumerate
96:
97: @menu
98: * License:: The GDB General Public License gives you permission
99: to redistribute GDB+ on certain terms; and also
100: explains that there is no warranty.
101: * Input:: GDB+ command syntax and input conventions.
102: * Files:: Specifying files for GDB+ to operate on.
103: * Options:: GDB+ arguments and options.
104: * Compilation::Compiling your program so you can debug it.
105: * Running:: Running your program under GDB+.
106: * Stopping:: Making your program stop. Why it may stop. What to do then.
107: * Stack:: Examining your program's stack.
108: * Source:: Examining your program's source files.
109: * Data:: Examining data in your program.
110: * Symbols:: Examining the debugger's symbol table.
111: * Altering:: Altering things in your program.
112: * Sequences:: Canned command sequences for repeated use.
113: * Emacs:: Using GDB through GNU Emacs.
114: * Remote:: Remote kernel debugging across a serial line.
115: * Commands:: Index of GDB+ commands.
116: * Concepts:: Index of GDB+ concepts.
117: @end menu
118:
119: @node License, Input, Top, Top
120: @unnumbered GDB General Public License
121: @center (Clarified 11 Feb 1988)
122:
123: The license agreements of most software companies keep you at the mercy
124: of those companies. By contrast, our general public license is intended to
125: give everyone the right to share GDB. To make sure that you get the rights
126: we want you to have, we need to make restrictions that forbid anyone to
127: deny you these rights or to ask you to surrender the rights. Hence this
128: license agreement.
129:
130: Specifically, we want to make sure that you have the right to give away
131: copies of GDB, that you receive source code or else can get it if you want
132: it, that you can change GDB or use pieces of it in new free programs, and
133: that you know you can do these things.
134:
135: To make sure that everyone has such rights, we have to forbid you to
136: deprive anyone else of these rights. For example, if you distribute copies
137: of GDB, you must give the recipients all the rights that you have. You
138: must make sure that they, too, receive or can get the source code. And you
139: must tell them their rights.
140:
141: Also, for our own protection, we must make certain that everyone finds
142: out that there is no warranty for GDB. If GDB is modified by someone else
143: and passed on, we want its recipients to know that what they have is not
144: what we distributed, so that any problems introduced by others will not
145: reflect on our reputation.
146:
147: Therefore we (Richard Stallman and the Free Software Foundation,
148: Inc.) make the following terms which say what you must do to be
149: allowed to distribute or change GDB.
150:
151: @unnumberedsec Copying Policies
152:
153: @enumerate
154: @item
155: You may copy and distribute verbatim copies of GDB source code as you
156: receive it, in any medium, provided that you conspicuously and
157: appropriately publish on each file a valid copyright notice ``Copyright
158: @copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year
159: is appropriate); keep intact the notices on all files that
160: refer to this License Agreement and to the absence of any warranty; and
161: give any other recipients of the GDB program a copy of this License
162: Agreement along with the program. You may charge a distribution fee
163: for the physical act of transferring a copy.
164:
165: @item
166: You may modify your copy or copies of GDB source code or any portion
167: of it, and copy and distribute such modifications under the terms of
168: Paragraph 1 above, provided that you also do the following:
169:
170: @itemize @bullet
171: @item
172: cause the modified files to carry prominent notices stating
173: that you changed the files and the date of any change; and
174:
175: @item
176: cause the whole of any work that you distribute or publish, that
177: in whole or in part contains or is a derivative of GDB or any
178: part thereof, to be licensed at no charge to all third parties on
179: terms identical to those contained in this License Agreement
180: (except that you may choose to grant more extensive warranty
181: protection to some or all third parties, at your option).
182:
183: @item
184: if the modified program serves as a debugger, cause it, when
185: started running in the simplest and usual way, to print an
186: announcement including a valid copyright notice ``Copyright
187: @copyright{} 1988 Free Software Foundation, Inc.'' (or with the
188: year that is appropriate), saying that there is no warranty (or
189: else, saying that you provide a warranty) and that users may
190: redistribute the program under these conditions, and telling the
191: user how to view a copy of this License Agreement.
192:
193: @item
194: You may charge a distribution fee for the physical act of
195: transferring a copy, and you may at your option offer warranty
196: protection in exchange for a fee.
197: @end itemize
198:
199: Mere aggregation of another unrelated program with this program (or its
200: derivative) on a volume of a storage or distribution medium does not bring
201: the other program under the scope of these terms.
202:
203: @item
204: You may copy and distribute GDB (or a portion or derivative of it,
205: under Paragraph 2) in object code or executable form under the terms
206: of Paragraphs 1 and 2 above provided that you also do one of the
207: following:
208:
209: @itemize @bullet
210: @item
211: accompany it with the complete corresponding machine-readable
212: source code, which must be distributed under the terms of
213: Paragraphs 1 and 2 above; or,
214:
215: @item
216: accompany it with a written offer, valid for at least three
217: years, to give any third party free (except for a nominal
218: shipping charge) a complete machine-readable copy of the
219: corresponding source code, to be distributed under the terms of
220: Paragraphs 1 and 2 above; or,
221:
222: @item
223: accompany it with the information you received as to where the
224: corresponding source code may be obtained. (This alternative is
225: allowed only for noncommercial distribution and only if you
226: received the program in object code or executable form alone.)
227: @end itemize
228:
229: For an executable file, complete source code means all the source code
230: for all modules it contains; but, as a special exception, it need not
231: include source code for modules which are standard libraries that
232: accompany the operating system on which the executable file runs.
233:
234: @item
235: You may not copy, sublicense, distribute or transfer GDB except as
236: expressly provided under this License Agreement. Any attempt
237: otherwise to copy, sublicense, distribute or transfer GDB is void and
238: your rights to use GDB under this License agreement shall be
239: automatically terminated. However, parties who have received computer
240: software programs from you with this License Agreement will not have
241: their licenses terminated so long as such parties remain in full
242: compliance.
243:
244: @item
245: If you wish to incorporate parts of GDB into other free programs whose
246: distribution conditions are different, write to the Free Software
247: Foundation. We have not yet worked out a simple rule that can be
248: stated here, but we will often permit this. We will be guided by the
249: two goals of preserving the free status of all derivatives our free
250: software and of promoting the sharing and reuse of software.
251: @end enumerate
252:
253: @iftex
254: @vfil
255: @eject
256: @end iftex
257: @unnumberedsec NO WARRANTY
258:
259: BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
260: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
261: WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
262: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB ``AS IS''
263: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
264: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
265: FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY
266: AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GDB
267: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
268: SERVICING, REPAIR OR CORRECTION.
269:
270: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
271: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
272: MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU
273: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
274: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
275: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
276: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
277: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
278: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
279: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
280: OTHER PARTY.
281:
282: @node Input, Files, License, Top
283: @chapter GDB+ Input Conventions
284:
285: GDB+ is invoked with the shell command @samp{gdb+}. Once started, it reads
286: commands from the terminal until you tell it to exit.
287:
288: A GDB+ command is a single line of input. There is no limit on how long
289: it can be. It starts with a command name, which is followed by arguments
290: whose meaning depends on the command name. Some command names do not
291: allow arguments.
292:
293: GDB+ command names may always be abbreviated if the abbreviation is
294: unambiguous. Sometimes even ambiguous abbreviations are allowed; for
295: example, @samp{s} is specially defined as equivalent to @samp{step}
296: even though there are other commands whose names start with @samp{s}.
297: Possible command abbreviations are often stated in the documentation
298: of the individual commands.
299:
300: A blank line as input to GDB+ means to repeat the previous command verbatim.
301: Certain commands do not allow themselves to be repeated this way; these are
302: commands for which unintentional repetition might cause trouble and which
303: you are unlikely to want to repeat. Certain others (@samp{list} and
304: @samp{x}) act differently when repeated because that is more useful.
305:
306: A line of input starting with @samp{#} is a comment; it does nothing.
307: This is useful mainly in command files (@xref{Command Files}).
308:
309: GDB+ @dfn{prompts} for commands with a string that is normally @samp{(gdb+)}.
310: When debugging GDB+ with GDB+, it is useful to change the prompt in one of
311: the GDB+s so that you can distinguish them. This can be done with the
312: @samp{set-prompt} command.
313:
314: @table @code
315: @item set-prompt @var{newprompt}
316: @kindex set-prompt
317: Directs GDB+ to use @var{newprompt} as its prompt string henceforth.
318: @end table
319:
320: @cindex exiting GDB+
321: @kindex quit
322: To exit GDB+, use the @samp{quit} command (abbreviated @samp{q}).
323: @kbd{Ctrl-c} will not exit from GDB+, but rather will terminate the action
324: of any GDB+ command that is in progress and return to GDB+ command level.
325: It is safe to type @kbd{Ctrl-c} at any time because GDB+ does not allow
326: it to take effect until a time when it is safe.
327:
328: @node Files, Options, Input, Top
329: @chapter Specifying GDB+'s Files
330:
331: @cindex core dump file
332: @cindex executable file
333: @cindex symbol table
334: GDB+ needs to know the filename of the program to be debugged. To debug a
335: core dump of a previous run, GDB+ must be told the filename of the core
336: dump.
337:
338: @menu
339: * Arguments: File Arguments. Specifying files with arguments
340: (when you start GDB+).
341: * Commands: File Commands. Specifying files with GDB+ commands.
342: @end menu
343:
344: @node File Arguments, File Commands, Files, Files
345: @section Specifying Files with Arguments
346:
347: The usual way to specify the executable and core dump file names is with
348: two command arguments given when you start GDB+. The first argument is used
349: as the file for execution and symbols, and the second argument (if any) is
350: used as the core dump file name. Thus,
351:
352: @example
353: GDB+ progm core
354: @end example
355:
356: @noindent
357: specifies @file{progm} as the executable program and @file{core} as a core
358: dump file to examine. (You do not need to have a core dump file if what
359: you plan to do is debug the program interactively.)
360:
361: @xref{Options}, for full information on command options and arguments for
362: GDB+.
363:
364: @node File Commands,, File Arguments, Files
365: @section Specifying Files with Commands
366:
367: Usually you specify the files for GDB+ to work with by giving arguments when
368: you invoke GDB+. But occasionally it is necessary to change to a different
369: file during a GDB+ session. Or you may run GDB+ and forget to specify the
370: files you want to use. In these situations the GDB+ commands to specify new
371: files are useful.
372:
373: @table @code
374: @item exec-file @var{filename}
375: @kindex exec-file
376: Specify that the program to be run is found in @var{filename}. If you
377: do not specify a directory and the file is not found in GDB+'s working
378: directory, GDB+ will use the environment variable @samp{PATH} as a list
379: of directories to search, just as the shell does when looking for a
380: program to run.
381:
382: @item symbol-file @var{filename}
383: @kindex symbol-file
384: Read symbol table information from file @var{filename}. @samp{PATH}
385: is searched when necessary. Most of the time you will use both the
386: @samp{exec-file} and @samp{symbol-file} commands on the same file.
387:
388: @samp{symbol-file} with no argument clears out GDB+'s symbol table.
389:
390: @item core-file @var{filename}
391: @kindex core-file
392: Specify the whereabouts of a core dump file to be used as the
393: ``contents of memory''. Note that the core dump contains only the
394: writable parts of memory; the read-only parts must come from the
395: executable file.
396:
397: @samp{core-file} with no argument specifies that no core file is
398: to be used.
399:
400: @item kill
401: @kindex kill
402: Cancel running the program under GDB+. This could be used if you wish
403: to debug a core dump instead. GDB+ ignores any core dump file if it is
404: actually running the program, so the @samp{kill} command is the only
405: sure way to go back to using the core dump file.
406:
407: @item info files
408: @kindex info files
409: Print the names of the executable and core dump files currently in
410: use by GDB+, and the file from which symbols were loaded.
411: @end table
412:
413: While all three file-specifying commands allow both absolute and relative
414: file names as arguments, GDB+ always converts the file name to an absolute
415: one and remembers it that way.
416:
417: The @samp{symbol-file} command causes GDB+ to forget the contents of its
418: convenience variables, the value history, and all breakpoints and
419: auto-display expressions. This is because they may contain pointers to the
420: internal data recording symbols and data types, which are part of the old
421: symbol table data being discarded inside GDB+.
422:
423: @node Options, Compilation, Files, Top
424: @chapter Options and Arguments for GDB+
425:
426: When you invoke GDB+, you can pass commands telling it what files to
427: operate on and what other things to do.
428:
429: @menu
430: * Mode Options:: Options controlling modes of operation.
431: * File Options:: Options to specify files (executable, coredump, commands)
432: * Other Arguments:: Any other arguments without options
433: also specify files.
434: @end menu
435:
436: @node Mode Options, File Options, Options, Options
437: @section Mode Options
438:
439: @table @samp
440: @item -nx
441: Do not execute commands from the init files @file{.gdbinit}.
442: Normally, the commands in these files are executed after all the
443: command options and arguments have been processed. @xref{Command
444: Files}.
445:
446: @item -q
447: ``Quiet''. Do not print the usual introductory messages.
448:
449: @item -batch
450: Run in batch mode. Exit with code 1 after processing all the command
451: files specified with @samp{-x} (and @file{./.gdbinit}, if not inhibited).
452: Exit also if, due to an error, GDB+ would otherwise attempt to read a
453: command from the terminal.
454:
455: @item -fullname
456: This option is used when Emacs runs GDB as a subprocess. It tells GDB
457: to output the full file name and line number in a standard,
458: recognizable fashion each time a stack frame is displayed (which
459: includes each time the program stops). This recognizable format looks
460: like two @samp{\032} characters, followed by the filename, line number
461: and character position separated by colons, and a newline. The
462: Emacs-to-GDB interface program uses the two @samp{\032} characters as
463: a signal to display the source code for the frame.
464: @end table
465:
466: @node File Options, Other Arguments, Mode Options, Options
467: @section File-specifying Options
468:
469: All the options and command line arguments given are processed
470: in sequential order. The order makes a difference when the
471: @samp{-x} command is used.
472:
473: @table @samp
474: @item -s @var{file}
475: Read symbol table from file @var{file}.
476:
477: @item -e @var{file}
478: Use file @var{file} as the executable file to execute when
479: appropriate, and for examining pure data in conjunction with a core
480: dump.
481:
482: @item -se @var{file}
483: Read symbol table from file @var{file} and use it as the executable
484: file.
485:
486: @item -c @var{file}
487: Use file @var{file} as a core dump to examine.
488:
489: @item -x @var{file}
490: Execute GDB+ commands from file @var{file}.
491:
492: @item -d @var{directory}
493: Add @var{directory} to the path to search for source files.
494: @end table
495:
496: @node Other Arguments,, File Options, Options
497: @section Other Arguments
498:
499: If there are arguments to GDB+ that are not options or associated with
500: options, the first one specifies the symbol table and executable file name
501: (as if it were preceded by @samp{-se}) and the second one specifies a core
502: dump file name (as if it were preceded by @samp{-c}).
503:
504: @node Compilation, Running, Options, Top
505: @chapter Compiling Your Program for Debugging
506:
507: In order to debug a program effectively, you need to ask for debugging
508: information when you compile it. This information in the object file
509: describes the data type of each variable or function and the correspondence
510: between source line numbers and addresses in the executable code.
511:
512: To request debugging information, specify the @samp{-g} option when you run
513: the compiler.
514:
515: The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options
516: together. This means that you cannot ask for optimization if you ask for
517: debugger information.
518:
519: The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it
520: possible to debug optimized code. We recommend that you @emph{always} use
521: @samp{-g} whenever you compile a program. You may think the program is
522: correct, but there's no sense in pushing your luck.
523:
524: If you are using the GNU C compiler, the GNU assembler and the GNU linker,
525: you can choose between two formats of debugging information: the standard
526: Unix format, which is what you get with @samp{-g}, and GDB's own format,
527: which you request by using @samp{-gg} instead of @samp{-g}. This stores
528: debugging information in the executable file in a format much like that
529: which is used inside GDB. This has these advantages and disadvantages:
530:
531: @itemize @bullet
532: @item
533: GDB can read @samp{-gg} format more than twice as fast as Unix
534: @samp{-g} format.
535:
536: @item
537: The @samp{-gg} format uses much more disk space than Unix format.
538:
539: @item
540: The Unix debuggers can understand only Unix format, so you cannot use
541: Unix source-level debuggers if you compile with @samp{-gg}. (The
542: @code{adb} debugger works with either format; it does not use this
543: information in any case.)
544: @end itemize
545:
546: @node Running, Stopping, Compilation, Top
547: @chapter Running Your Program Under GDB+
548:
549: @cindex running
550: @kindex run
551: To start your program under GDB+, use the @samp{run} command. The program
552: must already have been specified using the @samp{exec-file} command or with
553: an argument to GDB+ (@pxref{Files}); what @samp{run} does is create an
554: inferior process, load the program into it, and set it in motion.
555:
556: The execution of a program is affected by certain information it receives
557: from its superior. GDB+ provides ways to specify them, which you must do
558: @i{before} starting the program. (You can change them after starting the
559: program, but such changes do not affect the program unless you start it
560: over again.)
561:
562: @table @asis
563: @item The @i{arguments.}
564: You specify the arguments to give the program as the arguments of the
565: @samp{run} command.
566:
567: @item The @i{environment.}
568: The program normally inherits its environment from GDB+, but you can
569: use the GDB+ commands @samp{set-environment} and
570: @samp{unset-environment} to change parts of the environment that will
571: be given to the program.@refill
572:
573: @item The @i{working directory.}
574: The program inherits its working directory from GDB+. You can set GDB+'s
575: working directory with the @samp{cd} command in GDB+.
576: @end table
577:
578: After the @samp{run} command, the debugger does nothing but wait for your
579: program to stop. @xref{Stopping}.
580:
581: @menu
582: * Arguments:: Specifying the arguments for your program.
583: * Environment:: Specifying the environment for your program.
584: * Working Directory:: Specifying the working directory for giving
585: to your program when it is run.
586: * Input/Output:: Specifying the program's standard input and output.
587: * Attach:: Debugging a process started outside GDB.
588: @end menu
589:
590: @node Arguments, Environment, Running, Running
591: @section Your Program's Arguments
592:
593: @cindex arguments (to your program)
594: You specify the arguments to give the program as the arguments of the
595: @samp{run} command. They are passed to a shell, which expands wildcard
596: characters and performs redirection of I/O, and thence to the program.
597:
598: @samp{run} with no arguments uses the same arguments used by the previous
599: @samp{run}.
600:
601: @kindex set-args
602: The command @samp{set-args} can be used to specify the arguments to be used
603: the next time the program is run. If @samp{set-args} has no arguments, it
604: means to use no arguments the next time the program is run. If you have
605: run your program with arguments and want to run it again with no arguments,
606: this is the only way to do so.
607:
608: @node Environment, Working Directory, Arguments, Running
609: @section Your Program's Environment
610:
611: @cindex environment (of your program)
612: The @dfn{environment} consists of a set of @dfn{environment variables} and
613: their values. Environment variables conventionally record such things as
614: your user name, your home directory, your terminal type, and your search
615: path for programs to run. Usually you set up environment variables with
616: the shell and they are inherited by all the other programs you run. When
617: debugging, it can be useful to try running the program with different
618: environments without having to start the debugger over again.
619:
620: @table @code
621: @item info environment @var{varname}
622: @kindex info environment
623: Print the value of environment variable @var{varname} to be given to
624: your program when it is started. This command can be abbreviated
625: @samp{i env @var{varname}}.
626:
627: @item info environment
628: Print the names and values of all environment variables to be given to
629: your program when it is started. This command can be abbreviated
630: @samp{i env}.
631:
632: @item set-environment @var{varname} @var{value}
633: @kindex set-environment
634: Sets environment variable @var{varname} to @var{value}, for your
635: program only, not for GDB+ itself. @var{value} may be any string; the
636: values of environment variables are just strings, and any
637: interpretation is supplied by your program itself. This command
638: can be abbreviated as short as @samp{set-e}.
639:
640: @item unset-environment @var{varname}
641: @kindex unset-environment
642: Remove variable @var{varname} from the environment to be passed to
643: your program. This is different from @samp{set-env @var{varname} =}
644: because @samp{unset-environment} makes a variable not be defined at
645: all, which is distinguishable from an empty value. This command can
646: be abbreviated @samp{unset}.
647: @end table
648:
649: @node Working Directory, Input/Output, Environment, Running
650: @section Your Program's Working Directory
651:
652: @cindex working directory (of your program)
653: Each time you start your program with @samp{run}, it inherits its working
654: directory from the current working directory of GDB+. GDB+'s working
655: directory is initially whatever it inherited from its superior, but you can
656: specify the working directory for GDB+ with the @samp{cd} command.
657:
658: The GDB+ working directory also serves as a default for the commands
659: that specify files for GDB+ to operate on. @xref{Files}.
660:
661: @table @code
662: @item cd @var{directory}
663: @kindex cd
664: Set GDB+'s working directory to @var{directory}.
665:
666: @item pwd
667: @kindex pwd
668: Print GDB+'s working directory.
669: @end table
670:
671: @node Input/Output, Attach, Working Directory, Running
672: @section Your Program's Input and Output
673:
674: @cindex redirection
675: By default, the program you run under GDB does input and output to the same
676: terminal that GDB uses.
677:
678: You can redirect the program's input and/or output using @samp{sh}-style
679: redirection commands in the @samp{run} command. For example,
680:
681: @example
682: run > outfile
683: @end example
684:
685: @noindent
686: starts the program, diverting its output to the file @file{outfile}.
687:
688: @kindex tty
689: Another way to specify where the program should do input and output is with
690: the @samp{tty} command. This command accepts a file name as argument, and
691: causes this file to be the default for future @samp{run} commands. For
692: example,
693:
694: @example
695: tty /dev/ttyb
696: @end example
697:
698: @noindent
699: directs that processes started with subsequent @samp{run} commands default
700: to do input and output on the terminal @file{/dev/ttyb}. An explicit
701: redirection in @samp{run} overrides the @samp{tty} command.
702:
703: When you use the @samp{tty} command or redirect input in the @samp{run}
704: command, the @emph{input for your program} comes from the specified file,
705: but the input for GDB still comes from your terminal. The program's
706: controlling terminal is your (GDB's) terminal, not the terminal that the
707: program is reading from; so if you want to type @kbd{C-c} to stop the
708: program, you must type it on your (GDB's) terminal. A @kbd{C-c} typed on
709: the program's terminal is available to the program as ordinary input.
710:
711: @node Attach,, Input/Output, Running
712: @section Debugging an Already-Running Process
713: @kindex detach
714: @kindex attach
715: @cindex attach
716:
717: Some operating systems (in particular, Sun) allow GDB to begin debugging an
718: already-running process that was started outside of GDB. To do this you
719: must use the @samp{attach} command instead of the @samp{run} command.
720:
721: The @samp{attach} command requires one argument, which is the process-id of
722: the process you want to debug. (The usual way to find out the process-id
723: of the process is with the @samp{ps} utility.)
724:
725: The first thing GDB after arranging to debug the process is to stop it.
726: You can examine and modify an attached process with all the GDB commands
727: that ordinarily available when you start processes with @samp{run}. You
728: can insert breakpoints; you can step and continue; you can modify storage.
729: If you would rather the process continue running, use the @samp{continue}
730: command after attaching.
731:
732: When you are finished debugging the attached process, you can use the
733: @samp{detach} command to release it from GDB's control. Detaching
734: the process continues its execution. After the @samp{detach} command,
735: that process and GDB become completely independent once more, and you
736: are ready to @samp{attach} another process or start one with @samp{run}.
737:
738: If you exit GDB or use the @samp{run} command while you have an attached
739: process, you kill that process. You will be asked for confirmation if you
740: try to do either of these things.
741:
742: @node Stopping, Stack, Running, Top
743: @chapter Stopping and Continuing
744:
745: When you run a program normally, it runs until exiting. The purpose
746: of using a debugger is so that you can stop it before that point;
747: or so that if the program runs into trouble you can find out why.
748:
749: @menu
750: * Signals:: Fatal signals in your program just stop it;
751: then you can use GDB+ to see what is going on.
752: * Breakpoints:: Breakpoints let you stop your program when it
753: reaches a specified point in the code.
754: * Continuing:: Resuming execution until the next signal or breakpoint.
755: * Stepping:: Stepping runs the program a short distance and
756: then stops it wherever it has come to.
757: @end menu
758:
759: @node Signals, Breakpoints, Stopping, Stopping
760: @section Signals
761:
762: A signal is an asynchronous event that can happen in a program. The
763: operating system defines the possible kinds of signals, and gives each kind
764: a name and a number. For example, @code{SIGINT} is the signal a program
765: gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program
766: gets from referencing a place in memory far away from all the areas in use;
767: @code{SIGALRM} occurs when the alarm clock timer goes off (which happens
768: only if the program has requested an alarm).
769:
770: Some signals, including @code{SIGALRM}, are a normal part of the
771: functioning of the program. Others, such as @code{SIGSEGV}, indicate
772: errors; these signals are @dfn{fatal} (kill the program immediately) if the
773: program has not specified in advance some other way to handle the signal.
774: @code{SIGINT} does not indicate an error in the program, but it is normally
775: fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program.
776:
777: GDB+ has the ability to detect any occurrence of a signal in the program
778: running under GDB+'s control. You can tell GDB+ in advance what to do for
779: each kind of signal.
780:
781: Normally, GDB+ is set up to ignore non-erroneous signals like @code{SIGALRM}
782: (so as not to interfere with their role in the functioning of the program)
783: but to stop the program immediately whenever an error signal happens.
784: You can change these settings with the @samp{handle} command. You must
785: specify which signal you are talking about with its number.
786:
787: @table @code
788: @item info signal
789: @kindex info signal
790: Print a table of all the kinds of signals and how GDB+ has been told to
791: handle each one. You can use this to see the signal numbers of all
792: the defined types of signals.
793:
794: @item handle @var{signalnum} @var{keywords}@dots{}
795: @kindex handle
796: Change the way GDB+ handles signal @var{signalnum}. The @var{keywords}
797: say what change to make.
798: @end table
799:
800: To use the @samp{handle} command you must know the code number of the
801: signal you are concerned with. To find the code number, type @samp{info
802: signal} which prints a table of signal names and numbers.
803:
804: The keywords allowed by the handle command can be abbreviated. Their full
805: names are
806:
807: @table @code
808: @item stop
809: GDB+ should stop the program when this signal happens. This implies
810: the @samp{print} keyword as well.
811:
812: @item print
813: GDB+ should print a message when this signal happens.
814:
815: @item nostop
816: GDB+ should not stop the program when this signal happens. It may
817: still print a message telling you that the signal has come in.
818:
819: @item noprint
820: GDB+ should not mention the occurrence of the signal at all. This
821: implies the @samp{nostop} keyword as well.
822:
823: @item pass
824: GDB+ should allow the program to see this signal; the program will be
825: able to handle the signal, or may be terminated if the signal is fatal
826: and not handled.
827:
828: @item nopass
829: GDB+ should not allow the program to see this signal.
830: @end table
831:
832: When a signal has been set to stop the program, the program cannot see the
833: signal until you continue. It will see the signal then, if @samp{pass} is
834: in effect for the signal in question @i{at that time}. In other words,
835: after GDB+ reports a signal, you can use the @samp{handle} command with
836: @samp{pass} or @samp{nopass} to control whether that signal will be seen by
837: the program when you later continue it.
838:
839: You can also use the @samp{signal} command to prevent the program from
840: seeing a signal, or cause it to see a signal it normally would not see,
841: or to give it any signal at any time. @xref{Signaling}.
842:
843: @node Breakpoints, Continuing, Signals, Stopping
844: @section Breakpoints
845:
846: @cindex breakpoints
847: A @dfn{breakpoint} makes your program stop whenever a certain point in the
848: program is reached. You set breakpoints explicitly with GDB+ commands,
849: specifying the place where the program should stop by line number, function
850: name or exact address in the program. You can add various other conditions
851: to control whether the program will stop.
852:
853: Each breakpoint is assigned a number when it is created; these numbers are
854: successive integers starting with 1. In many of the commands for controlling
855: various features of breakpoints you use the breakpoint number to say which
856: breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
857: @dfn{disabled}; if disabled, it has no effect on the program until you
858: enable it again.
859:
860: @kindex info break
861: @kindex $_
862: The command @samp{info break} prints a list of all breakpoints set and not
863: cleared, showing their numbers, where in the program they are, and any
864: special features in use for them. Disabled breakpoints are included in the
865: list, but marked as disabled. @samp{info break} with a breakpoint number
866: as argument lists only that breakpoint. The convenience variable @samp{$_}
867: and the default examining-address for the @samp{x} command are set to the
868: address of the last breakpoint listed (@pxref{Memory}).
869:
870: @menu
871: * Set Breaks:: How to establish breakpoints.
872: * Clear Breaks:: How to remove breakpoints no longer needed.
873: * Disabling:: How to disable breakpoints (turn them off temporarily).
874: * Conditions:: Making extra conditions on whether to stop.
875: * Break Commands:: Commands to be executed at a breakpoint.
876: * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
877: @end menu
878:
879: @node Set Breaks, Clear Breaks, Breakpoints, Breakpoints
880: @subsection Setting Breakpoints
881:
882: @kindex break
883: Breakpoints are set with the @samp{break} command (abbreviated @samp{b}).
884: You have several ways to say where the breakpoint should go.
885:
886: @table @code
887: @item break @var{function}
888: Set a breakpoint at entry to function @var{function}.
889:
890: @item break @var{linenum}
891: Set a breakpoint at line @var{linenum} in the current source file.
892: That file is the last file whose source text was printed. This
893: breakpoint will stop the program just before it executes any of the
894: code on that line.
895:
896: @item break @var{filename}:@var{linenum}
897: Set a breakpoint at line @var{linenum} in source file @var{filename}.
898:
899: @item break @var{filename}:@var{function}
900: Set a breakpoint at entry to function @var{function} found in file
901: @var{filename}. Specifying a filename as well as a function name is
902: superfluous except when multiple files contain similarly named
903: functions.
904:
905: @item break *@var{address}
906: Set a breakpoint at address @var{address}. You can use this to set
907: breakpoints in parts of the program which do not have debugging
908: information or source files.
909:
910: @item break
911: Set a breakpoint at the next instruction to be executed in the
912: selected stack frame (@pxref{Stack}). This is a silly thing to do in
913: the innermost stack frame because the program would stop immediately
914: after being started, but it is very useful with another stack frame,
915: because it will cause the program to stop as soon as control returns
916: to that frame.
917:
918: @item break @dots{} if @var{cond}
919: Set a breakpoint with condition @var{cond}; evaluate the expression
920: @var{cond} each time the breakpoint is reached, and stop only if the
921: value is nonzero. @samp{@dots{}} stands for one of the possible
922: arguments described above (or no argument) specifying where to break.
923: @xref{Conditions}, for more information on breakpoint conditions.
924:
925: @item tbreak @var{args}
926: @kindex tbreak
927: Set a breakpoint enabled only for one stop. @var{args} are the
928: same as in the @samp{break} command, and the breakpoint is set in the same
929: way, but the breakpoint is automatically @dfn{disabled} the first time it
930: is hit.
931: @end table
932:
933: GDB allows you to set any number of breakpoints at the same place in the
934: program. There is nothing silly or meaningless about this. When the
935: breakpoints are conditional, this is even useful (@pxref{Conditions}).
936:
937: @node Clear Breaks, Disabling, Set Breaks, Breakpoints
938: @subsection Clearing Breakpoints
939:
940: @cindex clear breakpoint
941: @cindex delete breakpoints
942: It is often necessary to eliminate a breakpoint once it has done its job
943: and you no longer want the program to stop there. This is called
944: @dfn{clearing} or @samp{deleting} the breakpoint. A breakpoint that
945: has been cleared no longer exists in any sense.
946:
947: With the @samp{clear} command you can clear breakpoints according to where
948: they are in the program. With the @samp{delete} command you can clear
949: individual breakpoints by specifying their breakpoint numbers.
950:
951: @b{It is not necessary to clear a breakpoint to proceed past it.} GDB+
952: automatically ignores breakpoints in the first instruction to be executed
953: when you continue execution at the same address where the program stopped.
954:
955: @table @code
956: @item clear
957: @kindex clear
958: Clear any breakpoints at the next instruction to be executed in the
959: selected stack frame (@pxref{Selection}). When the innermost frame
960: is selected, this is a good way to clear a breakpoint that the program
961: just stopped at.
962:
963: @item clear @var{function}
964: @itemx clear @var{filename}:@var{function}
965: Clear any breakpoints set at entry to the function @var{function}.
966:
967: @item clear @var{linenum}
968: @item clear @var{filename}:@var{linenum}
969: Clear any breakpoints set at or within the code of the specified line.
970:
971: @item delete @var{bnums}@dots{}
972: @kindex delete
973: Delete the breakpoints of the numbers specified as arguments.
974: A breakpoint deleted is forgotten completely.
975: @end table
976:
977: @node Disabling, Conditions, Clear Breaks, Breakpoints
978: @subsection Disabling Breakpoints
979:
980: @cindex disabled breakpoints
981: @cindex enabled breakpoints
982: Rather than clearing a breakpoint, you might prefer to @dfn{disable} it.
983: This makes the breakpoint inoperative as if it had been cleared, but
984: remembers the information on the breakpoint so that you can @dfn{enable}
985: it again later.
986:
987: You disable and enable breakpoints with the @samp{enable} and
988: @samp{disable} commands, specifying one or more breakpoint numbers as
989: arguments. Use @samp{info break} to print a list of breakpoints if you
990: don't know which breakpoint numbers to use.
991:
992: A breakpoint can have any of four different states of enablement:
993:
994: @itemize @bullet
995: @item
996: Enabled. The breakpoint will stop the program. A breakpoint made
997: with the @samp{break} command starts out in this state.
998: @item
999: Disabled. The breakpoint has no effect on the program.
1000: @item
1001: Enabled once. The breakpoint will stop the program, but
1002: when it does so it will become disabled. A breakpoint made
1003: with the @samp{tbreak} command starts out in this state.
1004: @item
1005: Enabled for deletion. The breakpoint will stop the program, but
1006: immediately after it does so it will be deleted permanently.
1007: @end itemize
1008:
1009: You change the state of enablement of a breakpoint with the following
1010: commands:
1011:
1012: @table @code
1013: @item disable @var{bnums}@dots{}
1014: @kindex disable
1015: Disable the specified breakpoints. A disabled breakpoint has no
1016: effect but is not forgotten. All options such as ignore-counts,
1017: conditions and commands are remembered in case the breakpoint is
1018: enabled again later.
1019:
1020: @item enable @var{bnums}@dots{}
1021: @kindex enable
1022: Enable the specified breakpoints. They become effective once again in
1023: stopping the program, until you specify otherwise.
1024:
1025: @item enable once @var{bnums}@dots{}
1026: Enable the specified breakpoints temporarily. Each will be disabled
1027: again the next time it stops the program (unless you have used one of
1028: these commands to specify a different state before that time comes).
1029:
1030: @item enable delete @var{bnums}@dots{}
1031: Enable the specified breakpoints to work once and then die. Each of
1032: the breakpoints will be deleted the next time it stops the program
1033: (unless you have used one of these commands to specify a different
1034: state before that time comes).
1035: @end table
1036:
1037: Aside from the automatic disablement or deletion of a breakpoint when it
1038: stops the program, which happens only in certain states, the state of
1039: enablement of a breakpoint changes only when one of the commands above
1040: is used.
1041:
1042: @node Conditions, Break Commands, Disabling, Breakpoints
1043: @subsection Break Conditions
1044:
1045: @cindex conditions
1046: The simplest sort of breakpoint breaks every time the program reaches a
1047: specified place. You can also specify a @dfn{condition} for a breakpoint.
1048: A condition is just a boolean expression in your programming language.
1049: A breakpoint with a condition evaluates the expression each time the
1050: program reaches it, and the program stops only if the condition is true.
1051:
1052: Break conditions may have side effects, and may even call functions in your
1053: program. These may sound like strange things to do, but their effects are
1054: completely predictable unless there is another enabled breakpoint at the
1055: same address. (In that case, GDB+ might see the other breakpoint first and
1056: stop the program without checking the condition of this one.) Note that
1057: breakpoint commands are usually more convenient and flexible for the
1058: purpose of performing side effects when a breakpoint is reached
1059: (@pxref{Break Commands}).
1060:
1061: Break conditions can be specified when a breakpoint is set, by using
1062: @samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}.
1063: They can also be changed at any time with the @samp{condition} command:
1064:
1065: @table @code
1066: @item condition @var{bnum} @var{expression}
1067: @kindex condition
1068: Specify @var{expression} as the break condition for breakpoint number
1069: @var{bnum}. From now on, this breakpoint will stop the program only if
1070: the value of @var{expression} is true (nonzero, in C). @var{expression}
1071: is not evaluated at the time the @samp{condition} command is given.
1072:
1073: @item condition @var{bnum}
1074: Remove the condition from breakpoint number @var{bnum}. It becomes
1075: an ordinary unconditional breakpoint.
1076: @end table
1077:
1078: @cindex ignore count (of breakpoint)
1079: A special feature is provided for one kind of condition: to prevent the
1080: breakpoint from doing anything until it has been reached a certain number
1081: of times. This is done with the @dfn{ignore count} of the breakpoint.
1082: When the program reaches a breakpoint whose ignore count is positive, then
1083: instead of stopping, it just decrements the ignore count by one and
1084: continues.
1085:
1086: @table @code
1087: @item ignore @var{bnum} @var{count}
1088: @kindex ignore
1089: Set the ignore count of breakpoint number @var{bnum} to @var{count}.
1090: The next @var{count} times the breakpoint is reached, it will not stop.
1091:
1092: To make the breakpoint stop the next time it is reached, specify
1093: a count of zero.
1094:
1095: @item cont @var{count}
1096: Continue execution of the program, setting the ignore count of the
1097: breakpoint that the program stopped at to @var{count} minus one.
1098: Continuing through the breakpoint does not itself count as one of
1099: @var{count}. Thus, the program will not stop at this breakpoint until the
1100: @var{count}'th time it is hit.
1101:
1102: This command is allowed only when the program stopped due to a
1103: breakpoint. At other times, the argument to @samp{cont} is ignored.
1104: @end table
1105:
1106: If a breakpoint has a positive ignore count and a condition, the condition
1107: is not checked. Once the ignore count reaches zero, the condition will
1108: start to be checked.
1109:
1110: Note that you could achieve the effect of the ignore count with a condition
1111: such as @samp{$foo-- <= 0} using a debugger convenience variable that is
1112: decremented each time. That is why the ignore count is considered a
1113: special case of a condition. @xref{Convenience Vars}.
1114:
1115: @node Break Commands, Error in Breakpoints, Conditions, Breakpoints
1116: @subsection Commands Executed on Breaking
1117:
1118: @cindex breakpoint commands
1119: You can give any breakpoint a series of commands to execute when the
1120: program stops due to that breakpoint. For example, you might want to
1121: print the values of certain expressions, or enable other breakpoints.
1122:
1123: @table @code
1124: @item commands @var{bnum}
1125: Specify commands for breakpoint number @var{bnum}. The commands
1126: themselves appear on the following lines. Type a line containing just
1127: @samp{end} to terminate the commands.
1128:
1129: To remove all commands from a breakpoint, use the command
1130: @samp{commands} and follow it immediately by @samp{end}; that is, give
1131: no commands.
1132: @end table
1133:
1134: It is possible for breakpoint commands to start the program up again.
1135: Simply use the @samp{cont} command, or @samp{step}, or any other command
1136: to resume execution. However, any remaining breakpoint commands are
1137: ignored. When the program stops again, GDB+ will act according to why
1138: that stop took place.
1139:
1140: @kindex silent
1141: If the first command specified is @samp{silent}, the usual message about
1142: stopping at a breakpoint is not printed. This may be desirable for
1143: breakpoints that are to print a specific message and then continue.
1144: If the remaining commands too print nothing, you will see no sign that
1145: the breakpoint was reached at all. @samp{silent} is not really a command;
1146: it is meaningful only at the beginning of the commands for a breakpoint.
1147:
1148: The commands @samp{echo} and @samp{output} that allow you to print precisely
1149: controlled output are often useful in silent breakpoints. @xref{Output}.
1150:
1151: For example, here is how you could use breakpoint commands to print the
1152: value of @code{x} at entry to @code{foo} whenever it is positive. We
1153: assume that the newly created breakpoint is number 4; @samp{break} will
1154: print the number that is assigned.
1155:
1156: @example
1157: break foo if x>0
1158: commands 4
1159: silent
1160: echo x is\040
1161: output x
1162: echo \n
1163: cont
1164: end
1165: @end example
1166:
1167: One application for breakpoint commands is to correct one bug so you can
1168: test another. Put a breakpoint just after the erroneous line of code, give
1169: it a condition to detect the case in which something erroneous has been
1170: done, and give it commands to assign correct values to any variables that
1171: need them. End with the @samp{cont} command so that the program does not
1172: stop, and start with the @samp{silent} command so that no output is
1173: produced. Here is an example:
1174:
1175: @example
1176: break 403
1177: commands 5
1178: silent
1179: set x = y + 4
1180: cont
1181: end
1182: @end example
1183:
1184: One deficiency in the operation of automatically continuing breakpoints
1185: under Unix appears when your program uses raw mode for the terminal.
1186: GDB+ options back to its own terminal modes (not raw) before executing
1187: commands, and then must switch back to raw mode when your program is
1188: continued. This causes any pending terminal input to be lost.
1189:
1190: In the GNU system, this will be fixed by changing the behavior of
1191: terminal modes.
1192:
1193: Under Unix, when you have this problem, you might be able to get around
1194: it by putting your actions into the breakpoint condition instead of
1195: commands. For example
1196:
1197: @example
1198: condition 5 (x = y + 4), 0
1199: @end example
1200:
1201: @noindent
1202: is a condition expression that will change @code{x} as needed, then always
1203: have the value 0 so the program will not stop. Loss of input is avoided
1204: here because break conditions are evaluated without changing the terminal
1205: modes. When you want to have nontrivial conditions for performing the side
1206: effects, the operators @samp{&&}, @samp{||} and @samp{?@: @dots{} :@:} may be useful.
1207:
1208: @node Error in Breakpoints,, Break Commands, Breakpoints
1209: @subsection ``Cannot Insert Breakpoints'' Error
1210:
1211: Under Unix, breakpoints cannot be used in a program if any other process
1212: is running that program. Attempting to run or continue the program with
1213: a breakpoint in this case will cause GDB+ to stop it.
1214:
1215: When this happens, you have two ways to proceed:
1216:
1217: @enumerate
1218: @item
1219: Remove or disable the breakpoints, then continue.
1220:
1221: @item
1222: Suspend GDB+, and copy the file containing the program to a new name.
1223: Resume GDB+ and use the @samp{exec-file} command to specify that GDB+
1224: should run the program under that name. Then start the program again.
1225: @end enumerate
1226:
1227: @node Continuing, Stepping, Breakpoints, Stopping
1228: @section Continuing
1229:
1230: After your program stops, most likely you will want it to run some more if
1231: the bug you are looking for has not happened yet.
1232:
1233: @table @code
1234: @item cont
1235: Continue running the program at the place where it stopped.
1236: @end table
1237:
1238: If the program stopped at a breakpoint, the place to continue running
1239: is the address of the breakpoint. You might expect that continuing would
1240: just stop at the same breakpoint immediately. In fact, @samp{cont}
1241: takes special care to prevent that from happening. You do not need
1242: to clear the breakpoint to proceed through it after stopping at it.
1243:
1244: You can, however, specify an ignore-count for the breakpoint that the
1245: program stopped at, by means of an argument to the @samp{cont} command.
1246: @xref{Conditions}.
1247:
1248: If the program stopped because of a signal other than @code{SIGINT} or
1249: @code{SIGTRAP}, continuing will cause the program to see that signal.
1250: You may not want this to happen. For example, if the program stopped
1251: due to some sort of memory reference error, you might store correct
1252: values into the erroneous variables and continue, hoping to see more
1253: execution; but the program would probably terminate immediately as
1254: a result of the fatal signal once it sees the signal. To prevent this,
1255: you can continue with @samp{signal 0}. @xref{Signaling}. You can
1256: also act in advance to prevent the program from seeing certain kinds
1257: of signals, using the @samp{handle} command (@pxref{Signals}).
1258:
1259: @node Stepping,, Continuing, Stopping
1260: @section Stepping
1261:
1262: @cindex stepping
1263: @dfn{Stepping} means setting your program in motion for a limited time, so
1264: that control will return automatically to the debugger after one line of
1265: code or one machine instruction. Breakpoints are active during stepping
1266: and the program will stop for them even if it has not gone as far as the
1267: stepping command specifies.
1268:
1269: @table @code
1270: @item step
1271: @kindex step
1272: Proceed the program until control reaches a different line, then stop
1273: it and return to the debugger. This command is abbreviated @samp{s}.
1274:
1275: @item step @var{count}
1276: Proceed as in @samp{step}, but do so @var{count} times. If a breakpoint
1277: or a signal not related to stepping is reached before @var{count} steps,
1278: stepping stops right away.
1279:
1280: @item next
1281: @kindex next
1282: Similar to @samp{step}, but any function calls appearing within the line of
1283: code are executed without stopping. Execution stops when control reaches a
1284: different line of code at the stack level which was executing when the
1285: @samp{next} command was given. This command is abbreviated @samp{n}.
1286:
1287: An argument is a repeat count, as in @samp{step}.
1288:
1289: @item finish
1290: @kindex finish
1291: Continue running until just after the selected stack frame returns
1292: (or until there is some other reason to stop, such as a fatal signal
1293: or a breakpoint).
1294:
1295: Contrast this with the @samp{return} command (@pxref{Returning}).
1296:
1297: @item stepi
1298: @itemx si
1299: @kindex stepi
1300: @kindex si
1301: Proceed one machine instruction, then stop and return to the debugger.
1302:
1303: It is often useful to do @samp{display/i $pc} when stepping by machine
1304: instructions. This will cause the next instruction to be executed to
1305: be displayed automatically at each stop. @xref{Auto Display}.
1306:
1307: An argument is a repeat count, as in @samp{step}.
1308:
1309: @item nexti
1310: @itemx ni
1311: @kindex nexti
1312: @kindex ni
1313: Proceed one machine instruction, but if it is a subroutine call,
1314: proceed until the subroutine returns.
1315:
1316: An argument is a repeat count, as in @samp{next}.
1317: @end table
1318:
1319: A typical technique for using stepping is to put a breakpoint
1320: (@pxref{Breakpoints}) at the beginning of the function or the section of
1321: the program in which a problem is believed to lie, and then step through
1322: the suspect area, examining the variables that are interesting, until the
1323: problem happens.
1324:
1325: The @samp{cont} command can be used after stepping to resume execution
1326: until the next breakpoint or signal.
1327:
1328: @node Stack, Source, Stopping, Top
1329: @chapter Examining the Stack
1330:
1331: When your program has stopped, the first thing you need to know is where it
1332: stopped and how it got there.
1333:
1334: @cindex call stack
1335: Each time your program performs a function call, the information about
1336: where in the program the call was made from is saved in a block of data
1337: called a @dfn{stack frame}. The frame also contains the arguments of the
1338: call and the local variables of the function that was called. All the
1339: stack frames are allocated in a region of memory called the @dfn{call
1340: stack}.
1341:
1342: When your program stops, the GDB+ commands for examining the stack allow you
1343: to see all of this information.
1344:
1345: One of the stack frames is @dfn{selected} by GDB+ and many GDB+ commands
1346: refer implicitly to the selected frame. In particular, whenever you ask
1347: GDB+ for the value of a variable in the program, the value is found in the
1348: selected frame. There are special GDB+ commands to select whichever frame
1349: you are interested in.
1350:
1351: When the program stops, GDB+ automatically selects the currently executing
1352: frame and describes it briefly as the @samp{frame} command does
1353: (@pxref{Frame Info, Info}).
1354:
1355: @menu
1356: * Frames:: Explanation of stack frames and terminology.
1357: * Backtrace:: Summarizing many frames at once.
1358: * Selection:: How to select a stack frame.
1359: * Info: Frame Info, Commands to print information on stack frames.
1360: @end menu
1361:
1362: @node Frames, Backtrace, Stack, Stack
1363: @section Stack Frames
1364:
1365: @cindex frame
1366: The call stack is divided up into contiguous pieces called @dfn{frames};
1367: each frame is the data associated with one call to one function. The frame
1368: contains the arguments given to the function, the function's local
1369: variables, and the address at which the function is executing.
1370:
1371: @cindex initial frame
1372: @cindex outermost frame
1373: @cindex innermost frame
1374: When your program is started, the stack has only one frame, that of the
1375: function @code{main}. This is called the @dfn{initial} frame or the
1376: @dfn{outermost} frame. Each time a function is called, a new frame is
1377: made. Each time a function returns, the frame for that function invocation
1378: is eliminated. If a function is recursive, there can be many frames for
1379: the same function. The frame for the function in which execution is
1380: actually occurring is called the @dfn{innermost} frame. This is the most
1381: recently created of all the stack frames that still exist.
1382:
1383: @cindex frame pointer
1384: Inside your program, stack frames are identified by their addresses. A
1385: stack frame consists of many bytes, each of which has its own address; each
1386: kind of computer has a convention for choosing one of those bytes whose
1387: address serves as the address of the frame. Usually this address is kept
1388: in a register called the @dfn{frame pointer register} while execution is
1389: going on in that frame.
1390:
1391: @cindex frame number
1392: GDB+ assigns numbers to all existing stack frames, starting with zero for
1393: the innermost frame, one for the frame that called it, and so on upward.
1394: These numbers do not really exist in your program; they are to give you a
1395: way of talking about stack frames in GDB+ commands.
1396:
1397: @cindex selected frame
1398: Many GDB+ commands refer implicitly to one stack frame. GDB+ records a stack
1399: frame that is called the @dfn{selected} stack frame; you can select any
1400: frame using one set of GDB+ commands, and then other commands will operate
1401: on that frame. When your program stops, GDB+ automatically selects the
1402: innermost frame.
1403:
1404: @node Backtrace, Selection, Frames, Stack
1405: @section Backtraces
1406:
1407: A backtrace is a summary of how the program got where it is. It shows one
1408: line per frame, for many frames, starting with the currently executing
1409: frame (frame zero), followed by its caller (frame one), and on up the
1410: stack.
1411:
1412: @table @code
1413: @item backtrace
1414: @itemx bt
1415: Print a backtrace of the entire stack: one line per frame for all
1416: frames in the stack.
1417:
1418: You can stop the backtrace at any time by typing the system interrupt
1419: character, normally @kbd{Control-C}.
1420:
1421: @item backtrace @var{n}
1422: @itemx bt @var{n}
1423: Similar, but stop after @var{n} frames.
1424: @end table
1425:
1426: Each line in a backtrace shows the frame number, the program counter, the
1427: function and its arguments, and the source file name and line number (if
1428: known). The program counter is is omitted if is the beginning of the code for
1429: the source line. This is the same as the first of the two lines printed
1430: when you select a frame.
1431:
1432: @node Selection, Frame Info, Backtrace, Stack
1433: @section Selecting a Frame
1434:
1435: Most commands for examining the stack and other data in the program work on
1436: whichever stack frame is selected at the moment. Here are the commands for
1437: selecting a stack frame; all of them finish by printing a brief description
1438: of the stack frame just selected.
1439:
1440: @table @code
1441: @item frame @var{n}
1442: @kindex frame
1443: Select frame number @var{n}. Recall that frame zero is the innermost
1444: (currently executing) frame, frame one is the frame that called the
1445: innermost one, and so on. The highest-numbered frame is @code{main}'s
1446: frame.
1447:
1448: @item frame @var{addr}
1449: Select the frame at address @var{addr}. This is useful mainly if the
1450: chaining of stack frames has been damaged by a bug, making it
1451: impossible for GDB+ to assign numbers properly to all frames. In
1452: addition, this can be useful when the program has multiple stacks and
1453: options between them.
1454:
1455: @item up @var{n}
1456: @kindex up
1457: Select the frame @var{n} frames up from the frame previously selected.
1458: For positive numbers @var{n}, this advances toward the outermost
1459: frame, to higher frame numbers, to frames that have existed longer.
1460: @var{n} defaults to one.
1461:
1462: @item down @var{n}
1463: @kindex down
1464: Select the frame @var{n} frames down from the frame previously
1465: selected. For positive numbers @var{n}, this advances toward the
1466: innermost frame, to lower frame numbers, to frames that were created
1467: more recently. @var{n} defaults to one.
1468: @end table
1469:
1470: All of these commands end by printing some information on the frame that
1471: has been selected: the frame number, the function name, the arguments, the
1472: source file and line number of execution in that frame, and the text of
1473: that source line. For example:
1474:
1475: @example
1476: #3 main (argc=3, argv=??, env=??) at main.c, line 67
1477: 67 read_input_file (argv[i]);
1478: @end example
1479:
1480: After such a printout, the @samp{list} command with no arguments will print
1481: ten lines centered on the point of execution in the frame. @xref{List}.
1482:
1483: @node Frame Info,, Selection, Stack
1484: @section Information on a Frame
1485:
1486: There are several other commands to print information about the selected
1487: stack frame.
1488:
1489: @table @code
1490: @item frame
1491: This command prints a brief description of the selected stack frame.
1492: It can be abbreviated @samp{f}. With an argument, this command is
1493: used to select a stack frame; with no argument, it does not change
1494: which frame is selected, but still prints the same information.
1495:
1496: @item info frame
1497: @kindex info frame
1498: This command prints a verbose description of the selected stack frame,
1499: including the address of the frame, the addresses of the next frame in
1500: (called by this frame) and the next frame out (caller of this frame),
1501: the address of the frame's arguments, the program counter saved in it
1502: (the address of execution in the caller frame), and which registers
1503: were saved in the frame. The verbose description is useful when
1504: something has gone wrong that has made the stack format fail to fit
1505: the usual conventions.
1506:
1507: @item info frame @var{addr}
1508: Print a verbose description of the frame at address @var{addr},
1509: without selecting that frame. The selected frame remains unchanged by
1510: this command.
1511:
1512: @item info args
1513: @kindex info args
1514: Print the arguments of the selected frame, each on a separate line.
1515:
1516: @item info locals
1517: @kindex info locals
1518: Print the local variables of the selected frame, each on a separate
1519: line. These are all variables declared static or automatic within all
1520: program blocks that execution in this frame is currently inside of.
1521: @end table
1522:
1523: @node Source, Data, Stack, Top
1524: @chapter Examining Source Files
1525:
1526: GDB+ knows which source files your program was compiled from, and
1527: can print parts of their text. When your program stops, GDB+
1528: spontaneously prints the line it stopped in. Likewise, when you
1529: select a stack frame (@pxref{Selection}), GDB+ prints the line
1530: which execution in that frame has stopped in. You can also
1531: print parts of source files by explicit command.
1532:
1533: @menu
1534: * List:: Using the @samp{list} command to print source files.
1535: * Search:: Commands for searching source files.
1536: * Source Path:: Specifying the directories to search for source files.
1537: @end menu
1538:
1539: @node List, Search, Source, Source
1540: @section Printing Source Lines
1541:
1542: @kindex list
1543: To print lines from a source file, use the @samp{list} command
1544: (abbreviated @samp{l}). There are several ways to specify what part
1545: of the file you want to print.
1546:
1547: Here are the forms of @samp{list} command most commonly used:
1548:
1549: @table @code
1550: @item list @var{linenum}
1551: Print ten lines centered around line number @var{linenum} in the
1552: current source file.
1553:
1554: @item list @var{function}
1555: Print ten lines centered around the beginning of function
1556: @var{function}.
1557:
1558: @item list
1559: Print ten more lines. If the last lines printed were printed with a
1560: @samp{list} command, this prints ten lines following the last lines
1561: printed; however, if the last line printed was a solitary line printed
1562: as part of displaying a stack frame (@pxref{Stack}), this prints ten
1563: lines centered around that line.
1564:
1565: @item list @minus{}
1566: Print ten lines just before the lines last printed.
1567: @end table
1568:
1569: Repeating a @samp{list} command with @key{RET} discards the argument,
1570: so it is equivalent to typing just @samp{list}. This is more useful
1571: than listing the same lines again. An exception is made for an
1572: argument of @samp{-}; that argument is preserved in repetition so that
1573: each repetition moves up in the file.
1574:
1575: In general, the @samp{list} command expects you to supply zero, one or two
1576: @dfn{linespecs}. Linespecs specify source lines; there are several ways
1577: of writing them but the effect is always to specify some source line.
1578: Here is a complete description of the possible arguments for @samp{list}:
1579:
1580: @table @code
1581: @item list @var{linespec}
1582: Print ten lines centered around the line specified by @var{linespec}.
1583:
1584: @item list @var{first},@var{last}
1585: Print lines from @var{first} to @var{last}. Both arguments are
1586: linespecs.
1587:
1588: @item list ,@var{last}
1589: Print ten lines ending with @var{last}.
1590:
1591: @item list @var{first},
1592: Print ten lines starting with @var{first}.
1593:
1594: @item list +
1595: Print ten lines just after the lines last printed.
1596:
1597: @item list @minus{}
1598: Print ten lines just before the lines last printed.
1599:
1600: @item list
1601: As described in the preceding table.
1602: @end table
1603:
1604: Here are the ways of specifying a single source line---all the
1605: kinds of linespec.
1606:
1607: @table @asis
1608: @item @var{linenum}
1609: Specifies line @var{linenum} of the current source file.
1610: When a @samp{list} command has two linespecs, this refers to
1611: the same source file as the first linespec.
1612:
1613: @item +@var{offset}
1614: Specifies the line @var{offset} lines after the last line printed.
1615: When used as the second linespec in a @samp{list} command that has
1616: two, this specifies the line @var{offset} lines down from the
1617: first linespec.
1618:
1619: @item @minus{}@var{offset}
1620: Specifies the line @var{offset} lines before the last line printed.
1621:
1622: @item @var{filename}:@var{linenum}
1623: Specifies line @var{linenum} in the source file @var{filename}.
1624:
1625: @item @var{function}
1626: Specifies the line of the open-brace that begins the body of the
1627: function @var{function}.
1628:
1629: @item @var{filename}:@var{function}
1630: Specifies the line of the open-brace that begins the body of the
1631: function @var{function} in the file @var{filename}. The file name is
1632: needed with a function name only for disambiguation of identically
1633: named functions in different source files.
1634:
1635: @item *@var{address}
1636: Specifies the line containing the program address @var{address}.
1637: @var{address} may be any expression.
1638: @end table
1639:
1640: One other command is used to map source lines to program addresses.
1641:
1642: @table @code
1643: @item info line @var{linenum}
1644: @kindex info line
1645: Print the starting and ending addresses of the compiled code for
1646: source line @var{linenum}.
1647:
1648: @kindex $_
1649: The default examine address for the @samp{x} command is changed to the
1650: starting address of the line, so that @samp{x/i} is sufficient to
1651: begin examining the machine code (@pxref{Memory}). Also, this address
1652: is saved as the value of the convenience variable @samp{$_}
1653: (@pxref{Convenience Vars}).
1654: @end table
1655:
1656: @node Search, Source Path, List, Source
1657: @section Searching Source Files
1658: @cindex searching
1659: @kindex forward-search
1660: @kindex reverse-search
1661:
1662: There are two commands for searching through the current source file for a
1663: regular expression.
1664:
1665: The command @samp{forward-search @var{regexp}} checks each line, starting
1666: with the one following the last line listed, for a match for @var{regexp}.
1667: It lists the line that is found. You can abbreviate the command name
1668: as @samp{fo}.
1669:
1670: The command @samp{reverse-search @var{regexp}} checks each line, starting
1671: with the one before the last line listed and going backward, for a match
1672: for @var{regexp}. It lists the line that is found. You can abbreviate
1673: this command with as little as @samp{rev}.
1674:
1675: @node Source Path,, Search, Source
1676: @section Specifying Source Directories
1677:
1678: @cindex source path
1679: @cindex directories for source files
1680: Executable programs do not record the directories of the source files they
1681: were compiled from, just the names. GDB+ remembers a list of directories to
1682: search for source files; this is called the @dfn{source path}. Each time
1683: GDB+ wants a source file, it tries all the directories in the list, in the
1684: order they are present in the list, until it finds a file with the desired
1685: name.
1686:
1687: @kindex directory
1688: When you start GDB+, its source path contains just the current working
1689: directory. To add other directories, use the @samp{directory} command.
1690: @b{Note that the search path for executable files and the working directory
1691: are @i{not} used for finding source files.}
1692:
1693: @table @code
1694: @item directory @var{dirname}
1695: Add directory @var{dirname} to the end of the source path.
1696:
1697: @item directory
1698: Reset the source path to just the current working directory of GDB+.
1699: This requires confirmation.
1700:
1701: @samp{directory} with no argument can cause source files previously
1702: found by GDB+ to be found in a different directory. To make this work
1703: correctly, this command also clears out the tables GDB+ maintains
1704: about the source files it has already found.
1705:
1706: @item info directories
1707: @kindex info directories
1708: Print the source path: show which directories it contains.
1709: @end table
1710:
1711: Because the @samp{directory} command adds to the end of the source path,
1712: it does not affect any file that GDB+ has already found. If the source
1713: path contains directories that you do not want, and these directories
1714: contain misleading files with names matching your source files, the
1715: way to correct the situation is as follows:
1716:
1717: @enumerate
1718: @item
1719: Choose the directory you want at the beginning of the source path.
1720: Use the @samp{cd} command to make that the current working directory.
1721:
1722: @item
1723: Use @samp{directory} with no argument to reset the source path to just
1724: that directory.
1725:
1726: @item
1727: Use @samp{directory} with suitable arguments to add any other
1728: directories you want in the source path.
1729: @end enumerate
1730:
1731: @node Data, Symbols, Source, Top
1732: @chapter Examining Data
1733:
1734: @cindex printing data
1735: @cindex examining data
1736: @kindex print
1737: The usual way of examining data in your program is with the @samp{print}
1738: command (abbreviated @samp{p}). It evaluates and prints the value of any
1739: valid expression of the language the program is written in (for now, C).
1740: You type
1741:
1742: @example
1743: print @var{exp}
1744: @end example
1745:
1746: @noindent
1747: where @var{exp} is any valid expression, and the value of @var{exp}
1748: is printed in a format appropriate to its data type.
1749:
1750: A more low-level way of examining data is with the @samp{x} command.
1751: It examines data in memory at a specified address and prints it in a
1752: specified format.
1753:
1754: @menu
1755: * Expressions:: Expressions that can be computed and printed.
1756: * Variables:: Using your program's variables in expressions.
1757: * Assignment:: Setting your program's variables.
1758: * Arrays:: Examining part of memory as an array.
1759: * Formats:: Specifying formats for printing values.
1760: * Memory:: Examining memory explicitly.
1761: * Auto Display:: Printing certain expressions whenever program stops.
1762: * Value History:: Referring to values previously printed.
1763: * Convenience Vars:: Giving names to values for future reference.
1764: * Registers:: Referring to and storing in machine registers.
1765: @end menu
1766:
1767: @node Expressions, Variables, Data, Data
1768: @section Expressions
1769:
1770: @cindex expressions
1771: Many different GDB+ commands accept an expression and compute its value.
1772: Any kind of constant, variable or operator defined by the programming
1773: language you are using is legal in an expression in GDB+. This includes
1774: conditional expressions, function calls, casts and string constants.
1775:
1776: In addition to supporting operators normally found in the C programming
1777: language, GDB+ also supports some C++ constructs. For example, one can
1778: call member functions (GDB+ automatically uses @code{this} when necessary),
1779: and examine and manipulate pointers to members, pointers to member
1780: functions (virtual or otherwise).
1781:
1782: Casts are supported in all languages, not just in C, because it is so
1783: useful to cast a number into a pointer so as to examine a structure
1784: at that address in memory. GDB+ allows pointers to members and pointer to
1785: member functions to be cast to any type and vice-versa.
1786:
1787: GDB+ supports three kinds of operator in addition to those of programming
1788: languages:
1789:
1790: @table @code
1791: @item @@
1792: @samp{@@} is a binary operator for treating parts of memory as arrays.
1793: @xref{Arrays}, for more information.
1794:
1795: @item ::
1796: @samp{::} allows you to specify a variable in terms of the file or
1797: function it is defined in. @xref{Variables}. It also supports the C++
1798: convention of qualifying a variable reference according to a type name (or
1799: the global scope). This makes it easy to examing static class variables,
1800: for example.
1801:
1802: @item @{@var{type}@} @var{addr}
1803: Refers to an object of type @var{type} stored at address @var{addr} in
1804: memory. @var{addr} may be any expression whose value is an integer or
1805: pointer (but parentheses are required around nonunary operators, just as in
1806: a cast). This construct is allowed regardless of what kind of data is
1807: officially supposed to reside at @var{addr}.@refill
1808: @end table
1809:
1810: @node Variables, Arrays, Expressions, Data
1811: @section Program Variables
1812:
1813: The most common kind of expression to use is the name of a variable
1814: in your program.
1815:
1816: Variables in expressions are understood in the selected stack frame
1817: (@pxref{Selection}); they must either be global (or static) or be visible
1818: according to the scope rules of the programming language from the point of
1819: execution in that frame. This means that in the function
1820:
1821: @example
1822: foo (a)
1823: int a;
1824: @{
1825: bar (a);
1826: @{
1827: int b = test ();
1828: bar (b);
1829: @}
1830: @}
1831: @end example
1832:
1833: @noindent
1834: the variable @code{a} is usable whenever the program is executing
1835: within the function @code{foo}, but the variable @code{b} is visible
1836: only while the program is executing inside the block in which @code{b}
1837: is declared.
1838:
1839: @node Arrays, Formats, Variables, Data
1840: @section Artificial Arrays
1841:
1842: @cindex artificial array
1843: It is often useful to print out several successive objects of the
1844: same type in memory; a section of an array, or an array of
1845: dynamically determined size for which only a pointer exists in the
1846: program.
1847:
1848: This can be done by constructing an @dfn{artificial array} with the
1849: binary operator @samp{@@}. The left operand of @samp{@@} should be
1850: the first element of the desired array, as an individual object.
1851: The right operand should be the length of the array. The result is
1852: an array value whose elements are all of the type of the left argument.
1853: The first element is actually the left argument; the second element
1854: comes from bytes of memory immediately following those that hold the
1855: first element, and so on. Here is an example. If a program says
1856:
1857: @example
1858: int *array = (int *) malloc (len * sizeof (int));
1859: @end example
1860:
1861: @noindent
1862: you can print the contents of @code{array} with
1863:
1864: @example
1865: p *array@@len
1866: @end example
1867:
1868: The left operand of @samp{@@} must reside in memory. Array values made
1869: with @samp{@@} in this way behave just like other arrays in terms of
1870: subscripting, and are coerced to pointers when used in expressions.
1871: (It would probably appear in an expression via the value history,
1872: after you had printed it out.)
1873:
1874: @node Formats, Memory, Arrays, Data
1875: @section Formats
1876:
1877: @cindex formatted output
1878: @cindex output formats
1879: GDB+ normally prints all values according to their data types. Sometimes
1880: this is not what you want. For example, you might want to print a number
1881: in hex, or a pointer in decimal. Or you might want to view data in memory
1882: at a certain address as a character string or an instruction. These things
1883: can be done with @dfn{output formats}.
1884:
1885: The simplest use of output formats is to say how to print a value
1886: already computed. This is done by starting the arguments of the
1887: @samp{print} command with a slash and a format letter. The format
1888: letters supported are:
1889:
1890: @table @samp
1891: @item x
1892: Regard the bits of the value as an integer, and print the integer in
1893: hexadecimal.
1894:
1895: @item d
1896: Print as integer in signed decimal.
1897:
1898: @item u
1899: Print as integer in unsigned decimal.
1900:
1901: @item o
1902: Print as integer in octal.
1903:
1904: @item a
1905: Print as an address, both absolute in hex and then relative
1906: to a symbol defined as an address below it.
1907:
1908: @item c
1909: Regard as an integer and print it as a character constant.
1910:
1911: @item f
1912: Regard the bits of the value as a floating point number and print
1913: using typical floating point syntax.
1914: @end table
1915:
1916: For example, to print the program counter in hex (@pxref{Registers}), type
1917:
1918: @example
1919: p/x $pc
1920: @end example
1921:
1922: @noindent
1923: Note that no space is required before the slash; this is because command
1924: names in GDB+ cannot contain a slash.
1925:
1926: To reprint the last value in the value history with a different format,
1927: you can use the @samp{print} command with just a format and no
1928: expression. For example, @samp{p/x} reprints the last value in hex.
1929:
1930: @node Memory, Auto Display, Formats, Data
1931: @subsection Examining Memory
1932:
1933: @cindex examining memory
1934: @kindex x
1935: The command @samp{x} (for `examine') can be used to examine memory under
1936: explicit control of formats, without reference to the program's data types.
1937:
1938: @samp{x} is followed by a slash and an output format specification,
1939: followed by an expression for an address. The expression need not have
1940: a pointer value (though it may); it is used as an integer, as the
1941: address of a byte of memory.
1942:
1943: The output format in this case specifies both how big a unit of memory
1944: to examine and how to print the contents of that unit. It is done
1945: with one or two of the following letters:
1946:
1947: These letters specify just the size of unit to examine:
1948:
1949: @table @samp
1950: @item b
1951: Examine individual bytes.
1952:
1953: @item h
1954: Examine halfwords (two bytes each).
1955:
1956: @item w
1957: Examine words (four bytes each).
1958:
1959: @cindex word
1960: Many assemblers and cpu designers still use `word' for a 16-bit quantity,
1961: as a holdover from specific predecessor machines of the 1970's that really
1962: did use two-byte words. But more generally the term `word' has always
1963: referred to the size of quantity that a machine normally operates on and
1964: stores in its registers. This is 32 bits for all the machines that GNU
1965: runs on.
1966:
1967: @item g
1968: Examine giant words (8 bytes).
1969: @end table
1970:
1971: These letters specify just the way to print the contents:
1972:
1973: @table @samp
1974: @item x
1975: Print as integers in unsigned hexadecimal.
1976:
1977: @item d
1978: Print as integers in signed decimal.
1979:
1980: @item u
1981: Print as integers in unsigned decimal.
1982:
1983: @item o
1984: Print as integers in unsigned octal.
1985:
1986: @item a
1987: Print as an address, both absolute in hex and then relative
1988: to a symbol defined as an address below it.
1989:
1990: @item c
1991: Print as character constants.
1992:
1993: @item f
1994: Print as floating point. This works only with sizes @samp{w} and
1995: @samp{g}.
1996:
1997: @item s
1998: Print a null-terminated string of characters. The specified unit size
1999: is ignored; instead, the unit is however many bytes it takes to reach
2000: a null character (including the null character).
2001:
2002: @item i
2003: Print a machine instruction in assembler syntax (or nearly). The
2004: specified unit size is ignored; the number of bytes in an instruction
2005: varies depending on the type of machine, the opcode and the addressing
2006: modes used.
2007: @end table
2008:
2009: If either the manner of printing or the size of unit fails to be specified,
2010: the default is to use the same one that was used last. If you don't want
2011: to use any letters after the slash, you can omit the slash as well.
2012:
2013: You can also omit the address to examine. Then the address used is
2014: just after the last unit examined. This is why string and instruction
2015: formats actually compute a unit-size based on the data: so that the
2016: next string or instruction examined will start in the right place.
2017: The @samp{print} command sometimes sets the default address for
2018: the @samp{x} command; when the value printed resides in memory, the
2019: default is set to examine the same location. @samp{info line} also
2020: sets the default for @samp{x}, to the address of the start of the
2021: machine code for the specified line and @samp{info breakpoints} sets
2022: it to the address of the last breakpoint listed.
2023:
2024: When you use @key{RET} to repeat an @samp{x} command, it does not repeat
2025: exactly the same: the address specified previously (if any) is ignored, so
2026: that the repeated command examines the successive locations in memory
2027: rather than the same ones.
2028:
2029: You can examine several consecutive units of memory with one command by
2030: writing a repeat-count after the slash (before the format letters, if any).
2031: The repeat count must be a decimal integer. It has the same effect as
2032: repeating the @samp{x} command that many times except that the output may
2033: be more compact with several units per line.
2034:
2035: @example
2036: x/10i $pc
2037: @end example
2038:
2039: @noindent
2040: Prints ten instructions starting with the one to be executed next in the
2041: selected frame. After doing this, you could print another ten following
2042: instructions with
2043:
2044: @example
2045: x/10
2046: @end example
2047:
2048: @noindent
2049: in which the format and address are allowed to default.
2050:
2051: @kindex $_
2052: @kindex $__
2053: The addresses and contents printed by the @samp{x} command are not put in
2054: the value history because there is often too much of them and they would
2055: get in the way. Instead, GDB+ makes these values available for subsequent
2056: use in expressions as values of the convenience variables @samp{$_} and
2057: @samp{$__}.
2058:
2059: After an @samp{x} command, the last address examined is available for use
2060: in expressions in the convenience variable @samp{$_}. The contents of that
2061: address, as examined, are available in the convenience variable @samp{$__}.
2062:
2063: If the @samp{x} command has a repeat count, the address and contents saved
2064: are from the last memory unit printed; this is not the same as the last
2065: address printed if several units were printed on the last line of output.
2066:
2067: @node Auto Display, Value History, Memory, Data
2068: @section Automatic Display
2069:
2070: If you find that you want to print the value of an expression frequently
2071: (to see how it changes), you might want to add it to the @dfn{automatic
2072: display list} so that GDB+ will print its value each time the program stops.
2073: Each expression added to the list is given a number to identify it;
2074: to remove an expression from the list, you specify that number.
2075: The automatic display looks like this:
2076:
2077: @example
2078: 2: foo = 38
2079: 3: bar[5] = (struct hack *) 0x3804
2080: @end example
2081:
2082: @noindent
2083: showing item numbers, expressions and their current values.
2084:
2085: @table @code
2086: @item display @var{exp}
2087: @kindex display
2088: Add the expression @var{exp} to the list of expressions to display
2089: each time the program stops.
2090:
2091: @item display/@var{fmt} @var{exp}
2092: For @var{fmt} specifying only a display format and not a size or
2093: count, add the expression @var{exp} to the auto-display list but
2094: arranges to display it each time in the specified format @var{fmt}.
2095:
2096: @item display/@var{fmt} @var{addr}
2097: For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a
2098: number of units, add the expression @var{addr} as a memory address to
2099: be examined each time the program stops. Examining means in effect
2100: doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}.
2101:
2102: @item undisplay @var{n}
2103: @kindex undisplay
2104: Remove item number @var{n} from the list of expressions to display.
2105:
2106: @item display
2107: Display the current values of the expressions on the list, just as is
2108: done when the program stops.
2109:
2110: @item info display
2111: @kindex info display
2112: Print the list of expressions to display automatically, each one
2113: with its item number, but without showing the values.
2114: @end table
2115:
2116: @node Value History, Convenience Vars, Auto Display, Data
2117: @section Value History
2118:
2119: @cindex value history
2120: Every value printed by the @samp{print} command is saved for the entire
2121: session in GDB+'s @dfn{value history} so that you can refer to it in
2122: other expressions.
2123:
2124: @cindex $
2125: @cindex $$
2126: The values printed are given @dfn{history numbers} for you to refer to them
2127: by. These are successive integers starting with 1. @samp{print} shows you
2128: the history number assigned to a value by printing @samp{$@var{n} = }
2129: before the value; here @var{n} is the history number.
2130:
2131: To refer to any previous value, use @samp{$} followed by the value's
2132: history number. The output printed by @samp{print} is designed to remind
2133: you of this. Just @samp{$} refers to the most recent value in the history,
2134: and @samp{$$} refers to the value before that.
2135:
2136: For example, suppose you have just printed a pointer to a structure and
2137: want to see the contents of the structure. It suffices to type
2138:
2139: @example
2140: p *$
2141: @end example
2142:
2143: If you have a chain of structures where the component @samp{next} points
2144: to the next one, you can print the contents of the next one with
2145:
2146: @example
2147: p *$.next
2148: @end example
2149:
2150: It might be useful to repeat this command many times by typing @key{RET}.
2151:
2152: Note that the history records values, not expressions. If the value of
2153: @code{x} is 4 and you type
2154:
2155: @example
2156: print x
2157: set x=5
2158: @end example
2159:
2160: @noindent
2161: then the value recorded in the value history by the @samp{print} command
2162: remains 4 even though @code{x}'s value has changed.
2163:
2164: @table @code
2165: @item info history
2166: @kindex info history
2167: Print the last ten values in the value history, with their item
2168: numbers. This is like @samp{p $$9} repeated ten times, except that
2169: @samp{info history} does not change the history.
2170:
2171: @item info history @var{n}
2172: Print ten history values centered on history item number @var{n}.
2173: @end table
2174:
2175: @node Convenience Vars, Registers, Value History, Data
2176: @section Convenience Variables
2177:
2178: @cindex convenience variables
2179: GDB+ provides @dfn{convenience variables} that you can use within GDB+ to
2180: hold on to a value and refer to it later. These variables exist entirely
2181: within GDB+; they are not part of your program, and setting a convenience
2182: variable has no effect on further execution of your program. That's why
2183: you can use them freely.
2184:
2185: Convenience variables have names starting with @samp{$}. Any name starting
2186: with @samp{$} can be used for a convenience variable, unless it is one of
2187: the predefined set of register names (@pxref{Registers}).
2188:
2189: You can save a value in a convenience variable with an assignment
2190: expression, just as you would set a variable in your program. Example:
2191:
2192: @example
2193: set $foo = *object_ptr
2194: @end example
2195:
2196: @noindent
2197: would save in @samp{$foo} the value contained in the object pointed to by
2198: @code{object_ptr}.
2199:
2200: Using a convenience variable for the first time creates it; but its value
2201: is @code{void} until you assign a new value. You can alter the value with
2202: another assignment at any time.
2203:
2204: Convenience variables have no fixed types. You can assign a convenience
2205: variable any type of value, even if it already has a value of a different
2206: type. The convenience variable as an expression has whatever type its
2207: current value has.
2208:
2209: @table @code
2210: @item info convenience
2211: @kindex info convenience
2212: Print a list of convenience variables used so far, and their values.
2213: Abbreviated @samp{i con}.
2214: @end table
2215:
2216: One of the ways to use a convenience variable is as a counter to be
2217: incremented or a pointer to be advanced. For example:
2218:
2219: @example
2220: set $i = 0
2221: print bar[$i++]->contents
2222: @i{@dots{}repeat that command by typing @key{RET}.}
2223: @end example
2224:
2225: Some convenience variables are created automatically by GDB+ and given
2226: values likely to be useful.
2227:
2228: @table @samp
2229: @item $_
2230: The variable @samp{$_} is automatically set by the @samp{x} command to
2231: the last address examined (@pxref{Memory}). Other commands which
2232: provide a default address for @samp{x} to examine also set @samp{$_}
2233: to that address; these commands include @samp{info line} and @samp{info
2234: breakpoint}.
2235:
2236: @item $__
2237: The variable @samp{$__} is automatically set by the @samp{x} command
2238: to the value found in the last address examined.
2239: @end table
2240:
2241: @node Registers,, Convenience Vars, Data
2242: @section Registers
2243:
2244: @cindex registers
2245: Machine register contents can be referred to in expressions as variables
2246: with names starting with @samp{$}. The names of registers are different
2247: for each machine; use @samp{info registers} to see the names used on your
2248: machine. The names @samp{$pc} and @samp{$sp} are used on all machines for
2249: the program counter register and the stack pointer. Often @samp{$fp} is
2250: used for a register that contains a pointer to the current stack frame.
2251:
2252: GDB+ always considers the contents of an ordinary register as an integer
2253: when the register is examined in this way. Programs can store floating
2254: point values in registers also, but there is currently no GDB+ command
2255: to examine a specified register in floating point. (However, if the
2256: variable in your program which is stored in the register is a floating
2257: point variable, you can see the floating point value by examining
2258: the variable.)
2259:
2260: Some machines have special floating point registers. GDB+ considers these
2261: registers' values as floating point when you examine them explicitly.
2262:
2263: Some registers have distinct ``raw'' and ``virtual'' data formats. This
2264: means that the data format in which the register contents are saved by the
2265: operating system is not the same one that your program normally sees. For
2266: example, the registers of the 68881 floating point coprocessor are always
2267: saved in ``extended'' format, but all C programs expect to work with
2268: ``double'' format. In such cases, GDB+ normally works with the virtual
2269: format only (the format that makes sense for your program), but the
2270: @samp{info registers} command prints the data in both formats.
2271:
2272: Register values are relative to the selected stack frame
2273: (@pxref{Selection}). This means that you get the value that the register
2274: would contain if all stack frames farther in were exited and their saved
2275: registers restored. In order to see the real contents of all registers,
2276: you must select the innermost frame (with @samp{frame 0}).
2277:
2278: Some registers are never saved (typically those numbered zero or one)
2279: because they are used for returning function values; for these registers,
2280: relativization makes no difference.
2281:
2282: @table @code
2283: @item info registers
2284: @kindex info registers
2285: Print the names and relativized values of all registers.
2286:
2287: @item info registers @var{regname}
2288: Print the relativized value of register @var{regname}. @var{regname}
2289: may be any register name valid on the machine you are using, with
2290: or without the initial @samp{$}.
2291: @end table
2292:
2293: @subsection Examples
2294:
2295: You could print the program counter in hex with
2296:
2297: @example
2298: p/x $pc
2299: @end example
2300:
2301: @noindent
2302: or print the instruction to be executed next with
2303:
2304: @example
2305: x/i $pc
2306: @end example
2307:
2308: @noindent
2309: or add four to the stack pointer with
2310:
2311: @example
2312: set $sp += 4
2313: @end example
2314:
2315: @noindent
2316: The last is a way of removing one word from the stack, on machines where
2317: stacks grow downward in memory (most machines, nowadays). This assumes
2318: that the innermost stack frame is selected. Setting @samp{$sp} is
2319: not allowed when other stack frames are selected.
2320:
2321: @node Symbols, Altering, Data, Top
2322: @chapter Examining the Symbol Table
2323:
2324: The commands described in this section allow you to make inquiries for
2325: information about the symbols (names of variables, functions and types)
2326: defined in your program. This information is found by GDB+ in the symbol
2327: table loaded by the @samp{symbol-file} command; it is inherent in the text
2328: of your program and does not change as the program executes.
2329:
2330: @table @code
2331: @item whatis @var{exp}
2332: @kindex whatis
2333: Print the data type of expression @var{exp}. @var{exp} is not
2334: actually evaluated, and any side-effecting operations (such as
2335: assignments or function calls) inside it do not take place.
2336:
2337: @item whatis
2338: Print the data type of @samp{$}, the last value in the value history.
2339:
2340: @item info address @var{symbol}
2341: @kindex info address
2342: Describe where the data for @var{symbol} is stored. For register
2343: variables, this says which register. For other automatic variables,
2344: this prints the stack-frame offset at which the variable is always
2345: stored. Note the contrast with @samp{print &@var{symbol}}, which does
2346: not work at all for register variables and for automatic variables
2347: prints the exact address of the current instantiation of the variable.
2348:
2349: @item ptype @var{typename}
2350: @kindex ptype
2351: Print a description of data type @var{typename}. @var{typename} may be
2352: the name of a type, or for C code it may have the form
2353: @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
2354: @samp{enum @var{enum-tag}}.@refill
2355:
2356: @item info sources
2357: @kindex info sources
2358: Print the names of all source files in the program for which there
2359: is debugging information.
2360:
2361: @item info functions
2362: @kindex info functions
2363: Print the names and data types of all defined functions.
2364:
2365: @item info functions @var{regexp}
2366: Print the names and data types of all defined functions
2367: whose names contain a match for regular expression @var{regexp}.
2368: Thus, @samp{info fun step} finds all functions whose names
2369: include @samp{step}; @samp{info fun ^step} finds those whose names
2370: start with @samp{step}.
2371:
2372: @item info variables
2373: @kindex info variables
2374: Print the names and data types of all variables that are declared
2375: outside of functions.
2376:
2377: @item info variables @var{regexp}
2378: Print the names and data types of all variables, declared outside of
2379: functions, whose names contain a match for regular expression
2380: @var{regexp}.
2381:
2382: @item info types
2383: @kindex info types
2384: Print all data types that are defined in the program.
2385:
2386: @item info types @var{regexp}
2387: Print all data types that are defined in the program whose names
2388: contain a match for regular expression @var{regexp}.
2389:
2390: @item printsyms @var{filename}
2391: @kindex printsyms
2392: Write a complete dump of the debugger's symbol data into the
2393: file @var{filename}.
2394: @end table
2395:
2396: @node Altering, Sequences, Symbols, Top
2397: @chapter Altering Execution
2398:
2399: There are several ways to alter the execution of your program with GDB+
2400: commands.
2401:
2402: @menu
2403: * Assignment:: Altering variable values or memory contents.
2404: * Jumping:: Altering control flow.
2405: * Signaling:: Making signals happen in the program.
2406: * Returning:: Making a function return prematurely.
2407: @end menu
2408:
2409: @node Assignment, Jumping, Altering, Altering
2410: @section Assignment to Variables
2411:
2412: @cindex assignment
2413: @cindex setting variables
2414: To alter the value of a variable, evaluate an assignment expression.
2415: For example,
2416:
2417: @example
2418: print x=4
2419: @end example
2420:
2421: @noindent
2422: would store the value 4 into the variable @code{x}, and then print
2423: the value of the assignment expression (which is 4).
2424:
2425: @kindex set
2426: If you are not interested in seeing the value of the assignment, use the
2427: @samp{set} command instead of the @samp{print} command. @samp{set} is
2428: really the same as @samp{print} except that the expression's value is not
2429: printed and is not put in the value history (@pxref{Value History}). The
2430: expression is evaluated only for side effects.
2431:
2432: GDB+ allows more implicit conversions in assignments than C does; you can
2433: freely store an integer value into a pointer variable or vice versa, and
2434: any structure can be converted to any other structure that is the same
2435: length or shorter.
2436:
2437: In C, all the other assignment operators such as @samp{+=} and @samp{++}
2438: are supported as well.
2439:
2440: To store into arbitrary places in memory, use the @samp{@{@dots{}@}}
2441: construct to generate a value of specified type at a specified address
2442: (@pxref{Expressions}). For example,
2443:
2444: @example
2445: set @{int@}0x83040 = 4
2446: @end example
2447:
2448: @node Jumping, Signaling, Assignment, Altering
2449: @section Continuing at a Different Address
2450:
2451: @table @code
2452: @item jump @var{linenum}
2453: @kindex jump
2454: Resume execution at line number @var{linenum}. Execution may stop
2455: immediately if there is a breakpoint there.
2456:
2457: The @samp{jump} command does not change the current stack frame, or
2458: the stack pointer, or the contents of any memory location or any
2459: register other than the program counter. If line @var{linenum} is in
2460: a different function from the one currently executing, the results may
2461: be wild if the two functions expect different patterns of arguments or
2462: of local variables. For his reason, the @samp{jump} command requests
2463: confirmation if the specified line is not in the function currently
2464: executing. However, even wild results are predictable based on
2465: changing the program counter.
2466:
2467: @item jump *@var{address}
2468: Resume execution at the instruction at address @var{address}.
2469: @end table
2470:
2471: A similar effect can be obtained by storing a new value into the register
2472: @samp{$pc}, but not exactly the same.
2473:
2474: @example
2475: set $pc = 0x485
2476: @end example
2477:
2478: @noindent
2479: specifies the address at which execution will resume, but does not resume
2480: execution. That does not happen until you use the @samp{cont} command or a
2481: stepping command (@pxref{Stepping}).
2482:
2483: @node Signaling, Returning, Jumping, Altering
2484: @section Giving the Program a Signal
2485:
2486: @table @code
2487: @item signal @var{signalnum}
2488: @kindex signal
2489: Resume execution where the program stopped, but give it immediately
2490: the signal number @var{signalnum}.
2491:
2492: Alternatively, if @var{signalnum} is zero, continue execution and give
2493: no signal. This may be useful when the program has received a signal
2494: and the @samp{cont} command would allow the program to see that
2495: signal.
2496: @end table
2497:
2498: @node Returning,, Signaling, Altering
2499: @section Returning from a Function
2500:
2501: @cindex returning from a function
2502: @kindex return
2503: You can make any function call return immediately, using the @samp{return}
2504: command.
2505:
2506: First select the stack frame that you wish to return from
2507: (@pxref{Selection}). Then type the @samp{return} command. If you wish to
2508: specify the value to be returned, give that as an argument.
2509:
2510: This pops the selected stack frame (and any other frames inside of it),
2511: leaving its caller as the innermost remaining frame. That frame becomes
2512: selected. The specified value is stored in the registers used for
2513: returning values of functions.
2514:
2515: The @samp{return} command does not resume execution; it leaves the program
2516: stopped in the state that would exist if the function had just returned.
2517: Contrast this with the @samp{finish} command (@pxref{Stepping}), which
2518: resumes execution @i{until} the selected stack frame returns naturally.
2519:
2520: @node Sequences, Emacs, Altering, Top
2521: @chapter Canned Sequences of Commands
2522:
2523: GDB+ provides two ways to store sequences of commands for execution as a
2524: unit: user-defined commands and command files.
2525:
2526: @menu
2527: * Define:: User-defined commands.
2528: * Command Files:: Command files.
2529: * Output:: Controlled output commands useful in
2530: user-defined commands and command files.
2531: @end menu
2532:
2533: @node Define, Command Files, Sequences, Sequences
2534: @section User-Defined Commands
2535:
2536: @cindex user-defined commands
2537: A @dfn{user-defined command} is a sequence of GDB+ commands to which you
2538: assign a new name as a command. This is done with the @samp{define}
2539: command.
2540:
2541: @table @code
2542: @item define @var{commandname}
2543: @kindex define
2544: Define a command named @var{commandname}. If there is already a command
2545: by that name, you are asked to confirm that you want to redefine it.
2546:
2547: The definition of the command is made up of other GDB+ command lines,
2548: which are given following the @samp{define} command. The end of these
2549: commands is marked by a line containing @samp{end}.
2550:
2551: @item document @var{commandname}
2552: @kindex document
2553: Give documentation to the user-defined command @var{commandname}. The
2554: command @var{commandname} must already be defined. This command reads
2555: lines of documentation just as @samp{define} reads the lines of the
2556: command definition. After the @samp{document} command is finished,
2557: @samp{help} on command @var{commandname} will print the documentation
2558: you have specified.
2559:
2560: You may use the @samp{document} command again to change the
2561: documentation of a command. Redefining the command with @samp{define}
2562: does not change the documentation.
2563: @end table
2564:
2565: User-defined commands do not take arguments. When they are executed, the
2566: commands of the definition are not printed. An error in any command
2567: stops execution of the user-defined command.
2568:
2569: Commands that would ask for confirmation if used interactively proceed
2570: without asking when used inside a user-defined command. Many GDB+ commands
2571: that normally print messages to say what they are doing omit the messages
2572: when used in user-defined command.
2573:
2574: @node Command Files, Output, Define, Sequences
2575: @section Command Files
2576:
2577: @cindex command files
2578: A command file for GDB+ is a file of lines that are GDB+ commands. Comments
2579: (lines starting with @samp{#}) may also be included. An empty line in a
2580: command file does nothing; it does not mean to repeat the last command, as
2581: it would from the terminal.
2582:
2583: @cindex init file
2584: @cindex .gdbinit
2585: When GDB+ starts, it automatically executes its @dfn{init files}, command
2586: files named @file{.gdbinit}. GDB+ reads the init file (if any) in your home
2587: directory and then the init file (if any) in the current working
2588: directory. (The init files are not executed if the @samp{-nx} option
2589: is given.) You can also request the execution of a command file with the
2590: @samp{source} command:
2591:
2592: @table @code
2593: @item source @var{filename}
2594: @kindex source
2595: Execute the command file @var{filename}.
2596: @end table
2597:
2598: The lines in a command file are executed sequentially. They are not
2599: printed as they are executed. An error in any command terminates execution
2600: of the command file.
2601:
2602: Commands that would ask for confirmation if used interactively proceed
2603: without asking when used in a command file. Many GDB+ commands that
2604: normally print messages to say what they are doing omit the messages
2605: when used in a command file.
2606:
2607: @node Output,, Command Files, Sequences
2608: @section Commands for Controlled Output
2609:
2610: During the execution of a command file or a user-defined command, the only
2611: output that appears is what is explicitly printed by the commands of the
2612: definition. This section describes three commands useful for generating
2613: exactly the output you want.
2614:
2615: @table @code
2616: @item echo @var{text}
2617: @kindex echo
2618: Print @var{text}. Nonprinting characters can be included in
2619: @var{text} using C escape sequences, such as @samp{\n} to print a
2620: newline. @b{No newline will be printed unless you specify one.}
2621:
2622: A backslash at the end of @var{text} is ignored. It is useful for
2623: outputting a string ending in spaces, since trailing spaces are
2624: trimmed from all arguments. A backslash at the beginning preserves
2625: leading spaces in the same way, because @samp{\ } as an escape
2626: sequence stands for a space. Thus, to print @samp{ and foo = }, do
2627:
2628: @example
2629: echo \ and foo = \
2630: @end example
2631:
2632: @item output @var{expression}
2633: @kindex output
2634: Print the value of @var{expression} and nothing but that value: no
2635: newlines, no @samp{$@var{nn} = }. The value is not entered in the
2636: value history either.
2637:
2638: @item output/@var{fmt} @var{expression}
2639: Print the value of @var{expression} in format @var{fmt}.
2640: @xref{Formats}, for more information.
2641:
2642: @item printf @var{string}, @var{expressions}@dots{}
2643: @kindex printf
2644: Print the values of the @var{expressions} under the control of
2645: @var{string}. The @var{expressions} are separated by commas and may
2646: be either numbers or pointers. Their values are printed as specified
2647: by @var{string}, exactly as if the program were to execute
2648:
2649: @example
2650: printf (@var{string}, @var{expressions}@dots{});
2651: @end example
2652:
2653: For example, you can print two values in hex like this:
2654:
2655: @example
2656: printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
2657: @end example
2658:
2659: The only backslash-escape sequences that you can use in the string are
2660: the simple ones that consist of backslash followed by a letter.
2661: @end table
2662:
2663: @node Emacs, Remote, Sequences, Top
2664: @chapter Using GDB under GNU Emacs
2665:
2666: A special interface allows you to use GNU Emacs to view (and
2667: edit) the source files for the program you are debugging with
2668: GDB.
2669:
2670: To use this interface, use the command @kbd{M-x gdb} in Emacs.
2671: Give the executable file you want to debug as an argument. This
2672: command starts a GDB process as a subprocess of Emacs, with input
2673: and output through a newly created Emacs buffer.
2674:
2675: Using this GDB process is just like using GDB normally except for two things:
2676:
2677: @itemize @bullet
2678: @item
2679: All ``terminal'' input and output goes through the Emacs buffer. This
2680: applies both to GDB commands and their output, and to the input and
2681: output done by the program you are debugging.
2682:
2683: This is useful because it means that you can copy the text of previous
2684: commands and input them again; you can even use parts of the output
2685: in this way.
2686:
2687: All the facilities of Emacs's Shell mode are available for this purpose.
2688:
2689: @item
2690: GDB displays source code through Emacs. Each time GDB displays a
2691: stack frame, Emacs automatically finds the source file for that frame
2692: and puts an arrow (@samp{=>}) at the left margin of the current line.
2693:
2694: Explicit GDB @samp{list} or search commands still produce output as
2695: usual, but you probably will have no reason to use them.
2696: @end itemize
2697:
2698: In the GDB I/O buffer, you can use these special Emacs commands:
2699:
2700: @table @kbd
2701: @item M-s
2702: Execute to another source line, like the GDB @samp{step} command.
2703:
2704: @item M-n
2705: Execute to next source line in this function, skipping all function
2706: calls, like the GDB @samp{next} command.
2707:
2708: @item M-i
2709: Execute one instruction, like the GDB @samp{stepi} command.
2710:
2711: @item M-u
2712: Move up one stack frame (and display that frame's source file in
2713: Emacs), like the GDB @samp{up} command.
2714:
2715: @item M-d
2716: Move down one stack frame (and display that frame's source file in
2717: Emacs), like the GDB @samp{down} command. (This means that you cannot
2718: delete words in the usual fashion in the GDB buffer; I am guessing you
2719: won't often want to do that.)
2720:
2721: @item C-c C-f
2722: Execute until exit from the selected stack frame, like the GDB
2723: @samp{finish} command.
2724: @end table
2725:
2726: In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break})
2727: tells GDB to set a breakpoint on the source line point is on.
2728:
2729: The source files displayed in Emacs are in ordinary Emacs buffers
2730: which are visiting the source files in the usual way. You can edit
2731: the files with these buffers if you wish; but keep in mind that GDB
2732: communicates with Emacs in terms of line numbers. If you add or
2733: delete lines from the text, the line numbers that GDB knows will cease
2734: to correspond properly to the code.
2735:
2736: @node Remote, Commands, Emacs, Top
2737: @chapter Remote Kernel Debugging
2738:
2739: GDB has a special facility for debugging a remote machine via a serial
2740: connection. This can be used for kernel debugging.
2741:
2742: The program to be debugged on the remote machine needs to contain a
2743: debugging device driver which talks to GDB over the serial line using the
2744: protocol described below. The same version of GDB that is used ordinarily
2745: can be used for this.
2746:
2747: @menu
2748: * Remote Commands:: Commands used to start and finish remote debugging.
2749: @end menu
2750:
2751: For details of the communication protocol, see the comments in the GDB
2752: source file @file{remote.c}.
2753:
2754: @node Remote Commands,, Remote, Remote
2755: @section Commands for Remote Debugging
2756:
2757: To start remote debugging, first run GDB and specify as an executable file
2758: the program that is running in the remote machine. This tells GDB how
2759: to find the program's symbols and the contents of its pure text. Then
2760: establish communication using the @samp{attach} command with a device
2761: name rather than a pid as an argument. For example:
2762:
2763: @example
2764: attach /dev/ttyd
2765: @end example
2766:
2767: @noindent
2768: if the serial line is connected to the device named @file{/dev/ttyd}. This
2769: will stop the remote machine if it is not already stopped.
2770:
2771: Now you can use all the usual commands to examine and change data and to
2772: step and continue the remote program.
2773:
2774: To resume the remote program and stop debugging it, use the @samp{detach}
2775: command.
2776:
2777: @node Commands, Concepts, Remote, Top
2778: @unnumbered Command Index
2779:
2780: @printindex ky
2781:
2782: @node Concepts,, Commands, Top
2783: @unnumbered Concept Index
2784:
2785: @printindex cp
2786:
2787: @contents
2788: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.