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