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