Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / doc / gdb.texinfo
1 \input texinfo      @c -*-texinfo-*-
2 @c Copyright (C) 1988-2013 Free Software Foundation, Inc.
3 @c
4 @c %**start of header
5 @c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
6 @c of @set vars.  However, you can override filename with makeinfo -o.
7 @setfilename gdb.info
8 @c
9 @include gdb-cfg.texi
10 @c
11 @settitle Debugging with @value{GDBN}
12 @setchapternewpage odd
13 @c %**end of header
14
15 @iftex
16 @c @smallbook
17 @c @cropmarks
18 @end iftex
19
20 @finalout
21 @c To avoid file-name clashes between index.html and Index.html, when
22 @c the manual is produced on a Posix host and then moved to a
23 @c case-insensitive filesystem (e.g., MS-Windows), we separate the
24 @c indices into two: Concept Index and all the rest.
25 @syncodeindex ky fn
26 @syncodeindex tp fn
27
28 @c readline appendices use @vindex, @findex and @ftable,
29 @c annotate.texi and gdbmi use @findex.
30 @syncodeindex vr fn
31
32 @c !!set GDB manual's edition---not the same as GDB version!
33 @c This is updated by GNU Press.
34 @set EDITION Tenth
35
36 @c !!set GDB edit command default editor
37 @set EDITOR /bin/ex
38
39 @c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.
40
41 @c This is a dir.info fragment to support semi-automated addition of
42 @c manuals to an info tree.
43 @dircategory Software development
44 @direntry
45 * Gdb: (gdb).                     The GNU debugger.
46 @end direntry
47
48 @copying
49 Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
50
51 Permission is granted to copy, distribute and/or modify this document
52 under the terms of the GNU Free Documentation License, Version 1.3 or
53 any later version published by the Free Software Foundation; with the
54 Invariant Sections being ``Free Software'' and ``Free Software Needs
55 Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
56 and with the Back-Cover Texts as in (a) below.
57
58 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
59 this GNU Manual.  Buying copies from GNU Press supports the FSF in
60 developing GNU and promoting software freedom.''
61 @end copying
62
63 @ifnottex
64 This file documents the @sc{gnu} debugger @value{GDBN}.
65
66 This is the @value{EDITION} Edition, of @cite{Debugging with
67 @value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
68 @ifset VERSION_PACKAGE
69 @value{VERSION_PACKAGE}
70 @end ifset
71 Version @value{GDBVN}.
72
73 @insertcopying
74 @end ifnottex
75
76 @titlepage
77 @title Debugging with @value{GDBN}
78 @subtitle The @sc{gnu} Source-Level Debugger
79 @sp 1
80 @subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN}
81 @ifset VERSION_PACKAGE
82 @sp 1
83 @subtitle @value{VERSION_PACKAGE}
84 @end ifset
85 @author Richard Stallman, Roland Pesch, Stan Shebs, et al.
86 @page
87 @tex
88 {\parskip=0pt
89 \hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par
90 \hfill {\it Debugging with @value{GDBN}}\par
91 \hfill \TeX{}info \texinfoversion\par
92 }
93 @end tex
94
95 @vskip 0pt plus 1filll
96 Published by the Free Software Foundation @*
97 51 Franklin Street, Fifth Floor,
98 Boston, MA 02110-1301, USA@*
99 ISBN 978-0-9831592-3-0 @*
100
101 @insertcopying
102 @end titlepage
103 @page
104
105 @ifnottex
106 @node Top, Summary, (dir), (dir)
107
108 @top Debugging with @value{GDBN}
109
110 This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
111
112 This is the @value{EDITION} Edition, for @value{GDBN}
113 @ifset VERSION_PACKAGE
114 @value{VERSION_PACKAGE}
115 @end ifset
116 Version @value{GDBVN}.
117
118 Copyright (C) 1988-2013 Free Software Foundation, Inc.
119
120 This edition of the GDB manual is dedicated to the memory of Fred
121 Fish.  Fred was a long-standing contributor to GDB and to Free
122 software in general.  We will miss him.
123
124 @menu
125 * Summary::                     Summary of @value{GDBN}
126 * Sample Session::              A sample @value{GDBN} session
127
128 * Invocation::                  Getting in and out of @value{GDBN}
129 * Commands::                    @value{GDBN} commands
130 * Running::                     Running programs under @value{GDBN}
131 * Stopping::                    Stopping and continuing
132 * Reverse Execution::           Running programs backward
133 * Process Record and Replay::   Recording inferior's execution and replaying it
134 * Stack::                       Examining the stack
135 * Source::                      Examining source files
136 * Data::                        Examining data
137 * Optimized Code::              Debugging optimized code
138 * Macros::                      Preprocessor Macros
139 * Tracepoints::                 Debugging remote targets non-intrusively
140 * Overlays::                    Debugging programs that use overlays
141
142 * Languages::                   Using @value{GDBN} with different languages
143
144 * Symbols::                     Examining the symbol table
145 * Altering::                    Altering execution
146 * GDB Files::                   @value{GDBN} files
147 * Targets::                     Specifying a debugging target
148 * Remote Debugging::            Debugging remote programs
149 * Configurations::              Configuration-specific information
150 * Controlling GDB::             Controlling @value{GDBN}
151 * Extending GDB::               Extending @value{GDBN}
152 * Interpreters::                Command Interpreters
153 * TUI::                         @value{GDBN} Text User Interface
154 * Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs
155 * GDB/MI::                      @value{GDBN}'s Machine Interface.
156 * Annotations::                 @value{GDBN}'s annotation interface.
157 * JIT Interface::               Using the JIT debugging interface.
158 * In-Process Agent::            In-Process Agent
159
160 * GDB Bugs::                    Reporting bugs in @value{GDBN}
161
162 @ifset SYSTEM_READLINE
163 * Command Line Editing: (rluserman).         Command Line Editing
164 * Using History Interactively: (history).    Using History Interactively
165 @end ifset
166 @ifclear SYSTEM_READLINE
167 * Command Line Editing::        Command Line Editing
168 * Using History Interactively:: Using History Interactively
169 @end ifclear
170 * In Memoriam::                 In Memoriam
171 * Formatting Documentation::    How to format and print @value{GDBN} documentation
172 * Installing GDB::              Installing GDB
173 * Maintenance Commands::        Maintenance Commands
174 * Remote Protocol::             GDB Remote Serial Protocol
175 * Agent Expressions::           The GDB Agent Expression Mechanism
176 * Target Descriptions::         How targets can describe themselves to
177                                 @value{GDBN}
178 * Operating System Information:: Getting additional information from
179                                  the operating system
180 * Trace File Format::           GDB trace file format
181 * Index Section Format::        .gdb_index section format
182 * Copying::                     GNU General Public License says
183                                 how you can copy and share GDB
184 * GNU Free Documentation License::  The license for this documentation
185 * Concept Index::               Index of @value{GDBN} concepts
186 * Command and Variable Index::  Index of @value{GDBN} commands, variables,
187                                   functions, and Python data types
188 @end menu
189
190 @end ifnottex
191
192 @contents
193
194 @node Summary
195 @unnumbered Summary of @value{GDBN}
196
197 The purpose of a debugger such as @value{GDBN} is to allow you to see what is
198 going on ``inside'' another program while it executes---or what another
199 program was doing at the moment it crashed.
200
201 @value{GDBN} can do four main kinds of things (plus other things in support of
202 these) to help you catch bugs in the act:
203
204 @itemize @bullet
205 @item
206 Start your program, specifying anything that might affect its behavior.
207
208 @item
209 Make your program stop on specified conditions.
210
211 @item
212 Examine what has happened, when your program has stopped.
213
214 @item
215 Change things in your program, so you can experiment with correcting the
216 effects of one bug and go on to learn about another.
217 @end itemize
218
219 You can use @value{GDBN} to debug programs written in C and C@t{++}.
220 For more information, see @ref{Supported Languages,,Supported Languages}.
221 For more information, see @ref{C,,C and C++}.
222
223 Support for D is partial.  For information on D, see
224 @ref{D,,D}.
225
226 @cindex Modula-2
227 Support for Modula-2 is partial.  For information on Modula-2, see
228 @ref{Modula-2,,Modula-2}.
229
230 Support for OpenCL C is partial.  For information on OpenCL C, see
231 @ref{OpenCL C,,OpenCL C}.
232
233 @cindex Pascal
234 Debugging Pascal programs which use sets, subranges, file variables, or
235 nested functions does not currently work.  @value{GDBN} does not support
236 entering expressions, printing values, or similar features using Pascal
237 syntax.
238
239 @cindex Fortran
240 @value{GDBN} can be used to debug programs written in Fortran, although
241 it may be necessary to refer to some variables with a trailing
242 underscore.
243
244 @value{GDBN} can be used to debug programs written in Objective-C,
245 using either the Apple/NeXT or the GNU Objective-C runtime.
246
247 @menu
248 * Free Software::               Freely redistributable software
249 * Free Documentation::          Free Software Needs Free Documentation
250 * Contributors::                Contributors to GDB
251 @end menu
252
253 @node Free Software
254 @unnumberedsec Free Software
255
256 @value{GDBN} is @dfn{free software}, protected by the @sc{gnu}
257 General Public License
258 (GPL).  The GPL gives you the freedom to copy or adapt a licensed
259 program---but every person getting a copy also gets with it the
260 freedom to modify that copy (which means that they must get access to
261 the source code), and the freedom to distribute further copies.
262 Typical software companies use copyrights to limit your freedoms; the
263 Free Software Foundation uses the GPL to preserve these freedoms.
264
265 Fundamentally, the General Public License is a license which says that
266 you have these freedoms and that you cannot take these freedoms away
267 from anyone else.
268
269 @node Free Documentation
270 @unnumberedsec Free Software Needs Free Documentation
271
272 The biggest deficiency in the free software community today is not in
273 the software---it is the lack of good free documentation that we can
274 include with the free software.  Many of our most important
275 programs do not come with free reference manuals and free introductory
276 texts.  Documentation is an essential part of any software package;
277 when an important free software package does not come with a free
278 manual and a free tutorial, that is a major gap.  We have many such
279 gaps today.
280
281 Consider Perl, for instance.  The tutorial manuals that people
282 normally use are non-free.  How did this come about?  Because the
283 authors of those manuals published them with restrictive terms---no
284 copying, no modification, source files not available---which exclude
285 them from the free software world.
286
287 That wasn't the first time this sort of thing happened, and it was far
288 from the last.  Many times we have heard a GNU user eagerly describe a
289 manual that he is writing, his intended contribution to the community,
290 only to learn that he had ruined everything by signing a publication
291 contract to make it non-free.
292
293 Free documentation, like free software, is a matter of freedom, not
294 price.  The problem with the non-free manual is not that publishers
295 charge a price for printed copies---that in itself is fine.  (The Free
296 Software Foundation sells printed copies of manuals, too.)  The
297 problem is the restrictions on the use of the manual.  Free manuals
298 are available in source code form, and give you permission to copy and
299 modify.  Non-free manuals do not allow this.
300
301 The criteria of freedom for a free manual are roughly the same as for
302 free software.  Redistribution (including the normal kinds of
303 commercial redistribution) must be permitted, so that the manual can
304 accompany every copy of the program, both on-line and on paper.
305
306 Permission for modification of the technical content is crucial too.
307 When people modify the software, adding or changing features, if they
308 are conscientious they will change the manual too---so they can
309 provide accurate and clear documentation for the modified program.  A
310 manual that leaves you no choice but to write a new manual to document
311 a changed version of the program is not really available to our
312 community.
313
314 Some kinds of limits on the way modification is handled are
315 acceptable.  For example, requirements to preserve the original
316 author's copyright notice, the distribution terms, or the list of
317 authors, are ok.  It is also no problem to require modified versions
318 to include notice that they were modified.  Even entire sections that
319 may not be deleted or changed are acceptable, as long as they deal
320 with nontechnical topics (like this one).  These kinds of restrictions
321 are acceptable because they don't obstruct the community's normal use
322 of the manual.
323
324 However, it must be possible to modify all the @emph{technical}
325 content of the manual, and then distribute the result in all the usual
326 media, through all the usual channels.  Otherwise, the restrictions
327 obstruct the use of the manual, it is not free, and we need another
328 manual to replace it.
329
330 Please spread the word about this issue.  Our community continues to
331 lose manuals to proprietary publishing.  If we spread the word that
332 free software needs free reference manuals and free tutorials, perhaps
333 the next person who wants to contribute by writing documentation will
334 realize, before it is too late, that only free manuals contribute to
335 the free software community.
336
337 If you are writing documentation, please insist on publishing it under
338 the GNU Free Documentation License or another free documentation
339 license.  Remember that this decision requires your approval---you
340 don't have to let the publisher decide.  Some commercial publishers
341 will use a free license if you insist, but they will not propose the
342 option; it is up to you to raise the issue and say firmly that this is
343 what you want.  If the publisher you are dealing with refuses, please
344 try other publishers.  If you're not sure whether a proposed license
345 is free, write to @email{licensing@@gnu.org}.
346
347 You can encourage commercial publishers to sell more free, copylefted
348 manuals and tutorials by buying them, and particularly by buying
349 copies from the publishers that paid for their writing or for major
350 improvements.  Meanwhile, try to avoid buying non-free documentation
351 at all.  Check the distribution terms of a manual before you buy it,
352 and insist that whoever seeks your business must respect your freedom.
353 Check the history of the book, and try to reward the publishers that
354 have paid or pay the authors to work on it.
355
356 The Free Software Foundation maintains a list of free documentation
357 published by other publishers, at
358 @url{http://www.fsf.org/doc/other-free-books.html}.
359
360 @node Contributors
361 @unnumberedsec Contributors to @value{GDBN}
362
363 Richard Stallman was the original author of @value{GDBN}, and of many
364 other @sc{gnu} programs.  Many others have contributed to its
365 development.  This section attempts to credit major contributors.  One
366 of the virtues of free software is that everyone is free to contribute
367 to it; with regret, we cannot actually acknowledge everyone here.  The
368 file @file{ChangeLog} in the @value{GDBN} distribution approximates a
369 blow-by-blow account.
370
371 Changes much prior to version 2.0 are lost in the mists of time.
372
373 @quotation
374 @emph{Plea:} Additions to this section are particularly welcome.  If you
375 or your friends (or enemies, to be evenhanded) have been unfairly
376 omitted from this list, we would like to add your names!
377 @end quotation
378
379 So that they may not regard their many labors as thankless, we
380 particularly thank those who shepherded @value{GDBN} through major
381 releases:
382 Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
383 Jim Blandy (release 4.18);
384 Jason Molenda (release 4.17);
385 Stan Shebs (release 4.14);
386 Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
387 Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
388 John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
389 Jim Kingdon (releases 3.5, 3.4, and 3.3);
390 and Randy Smith (releases 3.2, 3.1, and 3.0).
391
392 Richard Stallman, assisted at various times by Peter TerMaat, Chris
393 Hanson, and Richard Mlynarik, handled releases through 2.8.
394
395 Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
396 in @value{GDBN}, with significant additional contributions from Per
397 Bothner and Daniel Berlin.  James Clark wrote the @sc{gnu} C@t{++}
398 demangler.  Early work on C@t{++} was by Peter TerMaat (who also did
399 much general update work leading to release 3.0).
400
401 @value{GDBN} uses the BFD subroutine library to examine multiple
402 object-file formats; BFD was a joint project of David V.
403 Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
404
405 David Johnson wrote the original COFF support; Pace Willison did
406 the original support for encapsulated COFF.
407
408 Brent Benson of Harris Computer Systems contributed DWARF 2 support.
409
410 Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
411 Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
412 support.
413 Jean-Daniel Fekete contributed Sun 386i support.
414 Chris Hanson improved the HP9000 support.
415 Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
416 David Johnson contributed Encore Umax support.
417 Jyrki Kuoppala contributed Altos 3068 support.
418 Jeff Law contributed HP PA and SOM support.
419 Keith Packard contributed NS32K support.
420 Doug Rabson contributed Acorn Risc Machine support.
421 Bob Rusk contributed Harris Nighthawk CX-UX support.
422 Chris Smith contributed Convex support (and Fortran debugging).
423 Jonathan Stone contributed Pyramid support.
424 Michael Tiemann contributed SPARC support.
425 Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
426 Pace Willison contributed Intel 386 support.
427 Jay Vosburgh contributed Symmetry support.
428 Marko Mlinar contributed OpenRISC 1000 support.
429
430 Andreas Schwab contributed M68K @sc{gnu}/Linux support.
431
432 Rich Schaefer and Peter Schauer helped with support of SunOS shared
433 libraries.
434
435 Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
436 about several machine instruction sets.
437
438 Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
439 remote debugging.  Intel Corporation, Wind River Systems, AMD, and ARM
440 contributed remote debugging modules for the i960, VxWorks, A29K UDI,
441 and RDI targets, respectively.
442
443 Brian Fox is the author of the readline libraries providing
444 command-line editing and command history.
445
446 Andrew Beers of SUNY Buffalo wrote the language-switching code, the
447 Modula-2 support, and contributed the Languages chapter of this manual.
448
449 Fred Fish wrote most of the support for Unix System Vr4.
450 He also enhanced the command-completion support to cover C@t{++} overloaded
451 symbols.
452
453 Hitachi America (now Renesas America), Ltd. sponsored the support for
454 H8/300, H8/500, and Super-H processors.
455
456 NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
457
458 Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
459 processors.
460
461 Toshiba sponsored the support for the TX39 Mips processor.
462
463 Matsushita sponsored the support for the MN10200 and MN10300 processors.
464
465 Fujitsu sponsored the support for SPARClite and FR30 processors.
466
467 Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
468 watchpoints.
469
470 Michael Snyder added support for tracepoints.
471
472 Stu Grossman wrote gdbserver.
473
474 Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
475 nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
476
477 The following people at the Hewlett-Packard Company contributed
478 support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0
479 (narrow mode), HP's implementation of kernel threads, HP's aC@t{++}
480 compiler, and the Text User Interface (nee Terminal User Interface):
481 Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
482 Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni.  Kim Haase
483 provided HP-specific information in this manual.
484
485 DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
486 Robert Hoehne made significant contributions to the DJGPP port.
487
488 Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
489 development since 1991.  Cygnus engineers who have worked on @value{GDBN}
490 fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
491 Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
492 Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
493 Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
494 Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni.  In
495 addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
496 JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
497 Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
498 Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
499 Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
500 Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
501 Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
502 Zuhn have made contributions both large and small.
503
504 Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
505 Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
506
507 Jim Blandy added support for preprocessor macros, while working for Red
508 Hat.
509
510 Andrew Cagney designed @value{GDBN}'s architecture vector.  Many
511 people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
512 Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
513 Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
514 Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
515 with the migration of old architectures to this new framework.
516
517 Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
518 unwinder framework, this consisting of a fresh new design featuring
519 frame IDs, independent frame sniffers, and the sentinel frame.  Mark
520 Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
521 libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
522 trad unwinders.  The architecture-specific changes, each involving a
523 complete rewrite of the architecture's frame code, were carried out by
524 Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
525 Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
526 Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
527 Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
528 Weigand.
529
530 Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
531 Tensilica, Inc.@: contributed support for Xtensa processors.  Others
532 who have worked on the Xtensa port of @value{GDBN} in the past include
533 Steve Tjiang, John Newlin, and Scott Foehner.
534
535 Michael Eager and staff of Xilinx, Inc., contributed support for the
536 Xilinx MicroBlaze architecture.
537
538 @node Sample Session
539 @chapter A Sample @value{GDBN} Session
540
541 You can use this manual at your leisure to read all about @value{GDBN}.
542 However, a handful of commands are enough to get started using the
543 debugger.  This chapter illustrates those commands.
544
545 @iftex
546 In this sample session, we emphasize user input like this: @b{input},
547 to make it easier to pick out from the surrounding output.
548 @end iftex
549
550 @c FIXME: this example may not be appropriate for some configs, where
551 @c FIXME...primary interest is in remote use.
552
553 One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
554 processor) exhibits the following bug: sometimes, when we change its
555 quote strings from the default, the commands used to capture one macro
556 definition within another stop working.  In the following short @code{m4}
557 session, we define a macro @code{foo} which expands to @code{0000}; we
558 then use the @code{m4} built-in @code{defn} to define @code{bar} as the
559 same thing.  However, when we change the open quote string to
560 @code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
561 procedure fails to define a new synonym @code{baz}:
562
563 @smallexample
564 $ @b{cd gnu/m4}
565 $ @b{./m4}
566 @b{define(foo,0000)}
567
568 @b{foo}
569 0000
570 @b{define(bar,defn(`foo'))}
571
572 @b{bar}
573 0000
574 @b{changequote(<QUOTE>,<UNQUOTE>)}
575
576 @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
577 @b{baz}
578 @b{Ctrl-d}
579 m4: End of input: 0: fatal error: EOF in string
580 @end smallexample
581
582 @noindent
583 Let us use @value{GDBN} to try to see what is going on.
584
585 @smallexample
586 $ @b{@value{GDBP} m4}
587 @c FIXME: this falsifies the exact text played out, to permit smallbook
588 @c FIXME... format to come out better.
589 @value{GDBN} is free software and you are welcome to distribute copies
590  of it under certain conditions; type "show copying" to see
591  the conditions.
592 There is absolutely no warranty for @value{GDBN}; type "show warranty"
593  for details.
594
595 @value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc...
596 (@value{GDBP})
597 @end smallexample
598
599 @noindent
600 @value{GDBN} reads only enough symbol data to know where to find the
601 rest when needed; as a result, the first prompt comes up very quickly.
602 We now tell @value{GDBN} to use a narrower display width than usual, so
603 that examples fit in this manual.
604
605 @smallexample
606 (@value{GDBP}) @b{set width 70}
607 @end smallexample
608
609 @noindent
610 We need to see how the @code{m4} built-in @code{changequote} works.
611 Having looked at the source, we know the relevant subroutine is
612 @code{m4_changequote}, so we set a breakpoint there with the @value{GDBN}
613 @code{break} command.
614
615 @smallexample
616 (@value{GDBP}) @b{break m4_changequote}
617 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
618 @end smallexample
619
620 @noindent
621 Using the @code{run} command, we start @code{m4} running under @value{GDBN}
622 control; as long as control does not reach the @code{m4_changequote}
623 subroutine, the program runs as usual:
624
625 @smallexample
626 (@value{GDBP}) @b{run}
627 Starting program: /work/Editorial/gdb/gnu/m4/m4
628 @b{define(foo,0000)}
629
630 @b{foo}
631 0000
632 @end smallexample
633
634 @noindent
635 To trigger the breakpoint, we call @code{changequote}.  @value{GDBN}
636 suspends execution of @code{m4}, displaying information about the
637 context where it stops.
638
639 @smallexample
640 @b{changequote(<QUOTE>,<UNQUOTE>)}
641
642 Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
643     at builtin.c:879
644 879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
645 @end smallexample
646
647 @noindent
648 Now we use the command @code{n} (@code{next}) to advance execution to
649 the next line of the current function.
650
651 @smallexample
652 (@value{GDBP}) @b{n}
653 882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
654  : nil,
655 @end smallexample
656
657 @noindent
658 @code{set_quotes} looks like a promising subroutine.  We can go into it
659 by using the command @code{s} (@code{step}) instead of @code{next}.
660 @code{step} goes to the next line to be executed in @emph{any}
661 subroutine, so it steps into @code{set_quotes}.
662
663 @smallexample
664 (@value{GDBP}) @b{s}
665 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
666     at input.c:530
667 530         if (lquote != def_lquote)
668 @end smallexample
669
670 @noindent
671 The display that shows the subroutine where @code{m4} is now
672 suspended (and its arguments) is called a stack frame display.  It
673 shows a summary of the stack.  We can use the @code{backtrace}
674 command (which can also be spelled @code{bt}), to see where we are
675 in the stack as a whole: the @code{backtrace} command displays a
676 stack frame for each active subroutine.
677
678 @smallexample
679 (@value{GDBP}) @b{bt}
680 #0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
681     at input.c:530
682 #1  0x6344 in m4_changequote (argc=3, argv=0x33c70)
683     at builtin.c:882
684 #2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
685 #3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
686     at macro.c:71
687 #4  0x79dc in expand_input () at macro.c:40
688 #5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
689 @end smallexample
690
691 @noindent
692 We step through a few more lines to see what happens.  The first two
693 times, we can use @samp{s}; the next two times we use @code{n} to avoid
694 falling into the @code{xstrdup} subroutine.
695
696 @smallexample
697 (@value{GDBP}) @b{s}
698 0x3b5c  532         if (rquote != def_rquote)
699 (@value{GDBP}) @b{s}
700 0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \
701 def_lquote : xstrdup(lq);
702 (@value{GDBP}) @b{n}
703 536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
704  : xstrdup(rq);
705 (@value{GDBP}) @b{n}
706 538         len_lquote = strlen(rquote);
707 @end smallexample
708
709 @noindent
710 The last line displayed looks a little odd; we can examine the variables
711 @code{lquote} and @code{rquote} to see if they are in fact the new left
712 and right quotes we specified.  We use the command @code{p}
713 (@code{print}) to see their values.
714
715 @smallexample
716 (@value{GDBP}) @b{p lquote}
717 $1 = 0x35d40 "<QUOTE>"
718 (@value{GDBP}) @b{p rquote}
719 $2 = 0x35d50 "<UNQUOTE>"
720 @end smallexample
721
722 @noindent
723 @code{lquote} and @code{rquote} are indeed the new left and right quotes.
724 To look at some context, we can display ten lines of source
725 surrounding the current line with the @code{l} (@code{list}) command.
726
727 @smallexample
728 (@value{GDBP}) @b{l}
729 533             xfree(rquote);
730 534
731 535         lquote = (lq == nil || *lq == '\0') ? def_lquote\
732  : xstrdup (lq);
733 536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
734  : xstrdup (rq);
735 537
736 538         len_lquote = strlen(rquote);
737 539         len_rquote = strlen(lquote);
738 540     @}
739 541
740 542     void
741 @end smallexample
742
743 @noindent
744 Let us step past the two lines that set @code{len_lquote} and
745 @code{len_rquote}, and then examine the values of those variables.
746
747 @smallexample
748 (@value{GDBP}) @b{n}
749 539         len_rquote = strlen(lquote);
750 (@value{GDBP}) @b{n}
751 540     @}
752 (@value{GDBP}) @b{p len_lquote}
753 $3 = 9
754 (@value{GDBP}) @b{p len_rquote}
755 $4 = 7
756 @end smallexample
757
758 @noindent
759 That certainly looks wrong, assuming @code{len_lquote} and
760 @code{len_rquote} are meant to be the lengths of @code{lquote} and
761 @code{rquote} respectively.  We can set them to better values using
762 the @code{p} command, since it can print the value of
763 any expression---and that expression can include subroutine calls and
764 assignments.
765
766 @smallexample
767 (@value{GDBP}) @b{p len_lquote=strlen(lquote)}
768 $5 = 7
769 (@value{GDBP}) @b{p len_rquote=strlen(rquote)}
770 $6 = 9
771 @end smallexample
772
773 @noindent
774 Is that enough to fix the problem of using the new quotes with the
775 @code{m4} built-in @code{defn}?  We can allow @code{m4} to continue
776 executing with the @code{c} (@code{continue}) command, and then try the
777 example that caused trouble initially:
778
779 @smallexample
780 (@value{GDBP}) @b{c}
781 Continuing.
782
783 @b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
784
785 baz
786 0000
787 @end smallexample
788
789 @noindent
790 Success!  The new quotes now work just as well as the default ones.  The
791 problem seems to have been just the two typos defining the wrong
792 lengths.  We allow @code{m4} exit by giving it an EOF as input:
793
794 @smallexample
795 @b{Ctrl-d}
796 Program exited normally.
797 @end smallexample
798
799 @noindent
800 The message @samp{Program exited normally.} is from @value{GDBN}; it
801 indicates @code{m4} has finished executing.  We can end our @value{GDBN}
802 session with the @value{GDBN} @code{quit} command.
803
804 @smallexample
805 (@value{GDBP}) @b{quit}
806 @end smallexample
807
808 @node Invocation
809 @chapter Getting In and Out of @value{GDBN}
810
811 This chapter discusses how to start @value{GDBN}, and how to get out of it.
812 The essentials are:
813 @itemize @bullet
814 @item
815 type @samp{@value{GDBP}} to start @value{GDBN}.
816 @item
817 type @kbd{quit} or @kbd{Ctrl-d} to exit.
818 @end itemize
819
820 @menu
821 * Invoking GDB::                How to start @value{GDBN}
822 * Quitting GDB::                How to quit @value{GDBN}
823 * Shell Commands::              How to use shell commands inside @value{GDBN}
824 * Logging Output::              How to log @value{GDBN}'s output to a file
825 @end menu
826
827 @node Invoking GDB
828 @section Invoking @value{GDBN}
829
830 Invoke @value{GDBN} by running the program @code{@value{GDBP}}.  Once started,
831 @value{GDBN} reads commands from the terminal until you tell it to exit.
832
833 You can also run @code{@value{GDBP}} with a variety of arguments and options,
834 to specify more of your debugging environment at the outset.
835
836 The command-line options described here are designed
837 to cover a variety of situations; in some environments, some of these
838 options may effectively be unavailable.
839
840 The most usual way to start @value{GDBN} is with one argument,
841 specifying an executable program:
842
843 @smallexample
844 @value{GDBP} @var{program}
845 @end smallexample
846
847 @noindent
848 You can also start with both an executable program and a core file
849 specified:
850
851 @smallexample
852 @value{GDBP} @var{program} @var{core}
853 @end smallexample
854
855 You can, instead, specify a process ID as a second argument, if you want
856 to debug a running process:
857
858 @smallexample
859 @value{GDBP} @var{program} 1234
860 @end smallexample
861
862 @noindent
863 would attach @value{GDBN} to process @code{1234} (unless you also have a file
864 named @file{1234}; @value{GDBN} does check for a core file first).
865
866 Taking advantage of the second command-line argument requires a fairly
867 complete operating system; when you use @value{GDBN} as a remote
868 debugger attached to a bare board, there may not be any notion of
869 ``process'', and there is often no way to get a core dump.  @value{GDBN}
870 will warn you if it is unable to attach or to read core dumps.
871
872 You can optionally have @code{@value{GDBP}} pass any arguments after the
873 executable file to the inferior using @code{--args}.  This option stops
874 option processing.
875 @smallexample
876 @value{GDBP} --args gcc -O2 -c foo.c
877 @end smallexample
878 This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set
879 @code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}.
880
881 You can run @code{@value{GDBP}} without printing the front material, which describes
882 @value{GDBN}'s non-warranty, by specifying @code{-silent}:
883
884 @smallexample
885 @value{GDBP} -silent
886 @end smallexample
887
888 @noindent
889 You can further control how @value{GDBN} starts up by using command-line
890 options.  @value{GDBN} itself can remind you of the options available.
891
892 @noindent
893 Type
894
895 @smallexample
896 @value{GDBP} -help
897 @end smallexample
898
899 @noindent
900 to display all available options and briefly describe their use
901 (@samp{@value{GDBP} -h} is a shorter equivalent).
902
903 All options and command line arguments you give are processed
904 in sequential order.  The order makes a difference when the
905 @samp{-x} option is used.
906
907
908 @menu
909 * File Options::                Choosing files
910 * Mode Options::                Choosing modes
911 * Startup::                     What @value{GDBN} does during startup
912 @end menu
913
914 @node File Options
915 @subsection Choosing Files
916
917 When @value{GDBN} starts, it reads any arguments other than options as
918 specifying an executable file and core file (or process ID).  This is
919 the same as if the arguments were specified by the @samp{-se} and
920 @samp{-c} (or @samp{-p}) options respectively.  (@value{GDBN} reads the
921 first argument that does not have an associated option flag as
922 equivalent to the @samp{-se} option followed by that argument; and the
923 second argument that does not have an associated option flag, if any, as
924 equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
925 If the second argument begins with a decimal digit, @value{GDBN} will
926 first attempt to attach to it as a process, and if that fails, attempt
927 to open it as a corefile.  If you have a corefile whose name begins with
928 a digit, you can prevent @value{GDBN} from treating it as a pid by
929 prefixing it with @file{./}, e.g.@: @file{./12345}.
930
931 If @value{GDBN} has not been configured to included core file support,
932 such as for most embedded targets, then it will complain about a second
933 argument and ignore it.
934
935 Many options have both long and short forms; both are shown in the
936 following list.  @value{GDBN} also recognizes the long forms if you truncate
937 them, so long as enough of the option is present to be unambiguous.
938 (If you prefer, you can flag option arguments with @samp{--} rather
939 than @samp{-}, though we illustrate the more usual convention.)
940
941 @c NOTE: the @cindex entries here use double dashes ON PURPOSE.  This
942 @c way, both those who look for -foo and --foo in the index, will find
943 @c it.
944
945 @table @code
946 @item -symbols @var{file}
947 @itemx -s @var{file}
948 @cindex @code{--symbols}
949 @cindex @code{-s}
950 Read symbol table from file @var{file}.
951
952 @item -exec @var{file}
953 @itemx -e @var{file}
954 @cindex @code{--exec}
955 @cindex @code{-e}
956 Use file @var{file} as the executable file to execute when appropriate,
957 and for examining pure data in conjunction with a core dump.
958
959 @item -se @var{file}
960 @cindex @code{--se}
961 Read symbol table from file @var{file} and use it as the executable
962 file.
963
964 @item -core @var{file}
965 @itemx -c @var{file}
966 @cindex @code{--core}
967 @cindex @code{-c}
968 Use file @var{file} as a core dump to examine.
969
970 @item -pid @var{number}
971 @itemx -p @var{number}
972 @cindex @code{--pid}
973 @cindex @code{-p}
974 Connect to process ID @var{number}, as with the @code{attach} command.
975
976 @item -command @var{file}
977 @itemx -x @var{file}
978 @cindex @code{--command}
979 @cindex @code{-x}
980 Execute commands from file @var{file}.  The contents of this file is
981 evaluated exactly as the @code{source} command would.
982 @xref{Command Files,, Command files}.
983
984 @item -eval-command @var{command}
985 @itemx -ex @var{command}
986 @cindex @code{--eval-command}
987 @cindex @code{-ex}
988 Execute a single @value{GDBN} command.
989
990 This option may be used multiple times to call multiple commands.  It may
991 also be interleaved with @samp{-command} as required.
992
993 @smallexample
994 @value{GDBP} -ex 'target sim' -ex 'load' \
995    -x setbreakpoints -ex 'run' a.out
996 @end smallexample
997
998 @item -init-command @var{file}
999 @itemx -ix @var{file}
1000 @cindex @code{--init-command}
1001 @cindex @code{-ix}
1002 Execute commands from file @var{file} before loading the inferior (but
1003 after loading gdbinit files).
1004 @xref{Startup}.
1005
1006 @item -init-eval-command @var{command}
1007 @itemx -iex @var{command}
1008 @cindex @code{--init-eval-command}
1009 @cindex @code{-iex}
1010 Execute a single @value{GDBN} command before loading the inferior (but
1011 after loading gdbinit files).
1012 @xref{Startup}.
1013
1014 @item -directory @var{directory}
1015 @itemx -d @var{directory}
1016 @cindex @code{--directory}
1017 @cindex @code{-d}
1018 Add @var{directory} to the path to search for source and script files.
1019
1020 @item -r
1021 @itemx -readnow
1022 @cindex @code{--readnow}
1023 @cindex @code{-r}
1024 Read each symbol file's entire symbol table immediately, rather than
1025 the default, which is to read it incrementally as it is needed.
1026 This makes startup slower, but makes future operations faster.
1027
1028 @end table
1029
1030 @node Mode Options
1031 @subsection Choosing Modes
1032
1033 You can run @value{GDBN} in various alternative modes---for example, in
1034 batch mode or quiet mode.
1035
1036 @table @code
1037 @anchor{-nx}
1038 @item -nx
1039 @itemx -n
1040 @cindex @code{--nx}
1041 @cindex @code{-n}
1042 Do not execute commands found in any initialization file.
1043 There are three init files, loaded in the following order:
1044
1045 @table @code
1046 @item @file{system.gdbinit}
1047 This is the system-wide init file.
1048 Its location is specified with the @code{--with-system-gdbinit}
1049 configure option (@pxref{System-wide configuration}).
1050 It is loaded first when @value{GDBN} starts, before command line options
1051 have been processed.
1052 @item @file{~/.gdbinit}
1053 This is the init file in your home directory.
1054 It is loaded next, after @file{system.gdbinit}, and before
1055 command options have been processed.
1056 @item @file{./.gdbinit}
1057 This is the init file in the current directory.
1058 It is loaded last, after command line options other than @code{-x} and
1059 @code{-ex} have been processed.  Command line options @code{-x} and
1060 @code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
1061 @end table
1062
1063 For further documentation on startup processing, @xref{Startup}.
1064 For documentation on how to write command files,
1065 @xref{Command Files,,Command Files}.
1066
1067 @anchor{-nh}
1068 @item -nh
1069 @cindex @code{--nh}
1070 Do not execute commands found in @file{~/.gdbinit}, the init file
1071 in your home directory.
1072 @xref{Startup}.
1073
1074 @item -quiet
1075 @itemx -silent
1076 @itemx -q
1077 @cindex @code{--quiet}
1078 @cindex @code{--silent}
1079 @cindex @code{-q}
1080 ``Quiet''.  Do not print the introductory and copyright messages.  These
1081 messages are also suppressed in batch mode.
1082
1083 @item -batch
1084 @cindex @code{--batch}
1085 Run in batch mode.  Exit with status @code{0} after processing all the
1086 command files specified with @samp{-x} (and all commands from
1087 initialization files, if not inhibited with @samp{-n}).  Exit with
1088 nonzero status if an error occurs in executing the @value{GDBN} commands
1089 in the command files.  Batch mode also disables pagination, sets unlimited
1090 terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm
1091 off} were in effect (@pxref{Messages/Warnings}).
1092
1093 Batch mode may be useful for running @value{GDBN} as a filter, for
1094 example to download and run a program on another computer; in order to
1095 make this more useful, the message
1096
1097 @smallexample
1098 Program exited normally.
1099 @end smallexample
1100
1101 @noindent
1102 (which is ordinarily issued whenever a program running under
1103 @value{GDBN} control terminates) is not issued when running in batch
1104 mode.
1105
1106 @item -batch-silent
1107 @cindex @code{--batch-silent}
1108 Run in batch mode exactly like @samp{-batch}, but totally silently.  All
1109 @value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
1110 unaffected).  This is much quieter than @samp{-silent} and would be useless
1111 for an interactive session.
1112
1113 This is particularly useful when using targets that give @samp{Loading section}
1114 messages, for example.
1115
1116 Note that targets that give their output via @value{GDBN}, as opposed to
1117 writing directly to @code{stdout}, will also be made silent.
1118
1119 @item -return-child-result
1120 @cindex @code{--return-child-result}
1121 The return code from @value{GDBN} will be the return code from the child
1122 process (the process being debugged), with the following exceptions:
1123
1124 @itemize @bullet
1125 @item
1126 @value{GDBN} exits abnormally.  E.g., due to an incorrect argument or an
1127 internal error.  In this case the exit code is the same as it would have been
1128 without @samp{-return-child-result}.
1129 @item
1130 The user quits with an explicit value.  E.g., @samp{quit 1}.
1131 @item
1132 The child process never runs, or is not allowed to terminate, in which case
1133 the exit code will be -1.
1134 @end itemize
1135
1136 This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
1137 when @value{GDBN} is being used as a remote program loader or simulator
1138 interface.
1139
1140 @item -nowindows
1141 @itemx -nw
1142 @cindex @code{--nowindows}
1143 @cindex @code{-nw}
1144 ``No windows''.  If @value{GDBN} comes with a graphical user interface
1145 (GUI) built in, then this option tells @value{GDBN} to only use the command-line
1146 interface.  If no GUI is available, this option has no effect.
1147
1148 @item -windows
1149 @itemx -w
1150 @cindex @code{--windows}
1151 @cindex @code{-w}
1152 If @value{GDBN} includes a GUI, then this option requires it to be
1153 used if possible.
1154
1155 @item -cd @var{directory}
1156 @cindex @code{--cd}
1157 Run @value{GDBN} using @var{directory} as its working directory,
1158 instead of the current directory.
1159
1160 @item -data-directory @var{directory}
1161 @cindex @code{--data-directory}
1162 Run @value{GDBN} using @var{directory} as its data directory.
1163 The data directory is where @value{GDBN} searches for its
1164 auxiliary files.  @xref{Data Files}.
1165
1166 @item -fullname
1167 @itemx -f
1168 @cindex @code{--fullname}
1169 @cindex @code{-f}
1170 @sc{gnu} Emacs sets this option when it runs @value{GDBN} as a
1171 subprocess.  It tells @value{GDBN} to output the full file name and line
1172 number in a standard, recognizable fashion each time a stack frame is
1173 displayed (which includes each time your program stops).  This
1174 recognizable format looks like two @samp{\032} characters, followed by
1175 the file name, line number and character position separated by colons,
1176 and a newline.  The Emacs-to-@value{GDBN} interface program uses the two
1177 @samp{\032} characters as a signal to display the source code for the
1178 frame.
1179
1180 @item -annotate @var{level}
1181 @cindex @code{--annotate}
1182 This option sets the @dfn{annotation level} inside @value{GDBN}.  Its
1183 effect is identical to using @samp{set annotate @var{level}}
1184 (@pxref{Annotations}).  The annotation @var{level} controls how much
1185 information @value{GDBN} prints together with its prompt, values of
1186 expressions, source lines, and other types of output.  Level 0 is the
1187 normal, level 1 is for use when @value{GDBN} is run as a subprocess of
1188 @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
1189 that control @value{GDBN}, and level 2 has been deprecated.
1190
1191 The annotation mechanism has largely been superseded by @sc{gdb/mi}
1192 (@pxref{GDB/MI}).
1193
1194 @item --args
1195 @cindex @code{--args}
1196 Change interpretation of command line so that arguments following the
1197 executable file are passed as command line arguments to the inferior.
1198 This option stops option processing.
1199
1200 @item -baud @var{bps}
1201 @itemx -b @var{bps}
1202 @cindex @code{--baud}
1203 @cindex @code{-b}
1204 Set the line speed (baud rate or bits per second) of any serial
1205 interface used by @value{GDBN} for remote debugging.
1206
1207 @item -l @var{timeout}
1208 @cindex @code{-l}
1209 Set the timeout (in seconds) of any communication used by @value{GDBN}
1210 for remote debugging.
1211
1212 @item -tty @var{device}
1213 @itemx -t @var{device}
1214 @cindex @code{--tty}
1215 @cindex @code{-t}
1216 Run using @var{device} for your program's standard input and output.
1217 @c FIXME: kingdon thinks there is more to -tty.  Investigate.
1218
1219 @c resolve the situation of these eventually
1220 @item -tui
1221 @cindex @code{--tui}
1222 Activate the @dfn{Text User Interface} when starting.  The Text User
1223 Interface manages several text windows on the terminal, showing
1224 source, assembly, registers and @value{GDBN} command outputs
1225 (@pxref{TUI, ,@value{GDBN} Text User Interface}).  Do not use this
1226 option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
1227 Using @value{GDBN} under @sc{gnu} Emacs}).
1228
1229 @c @item -xdb
1230 @c @cindex @code{--xdb}
1231 @c Run in XDB compatibility mode, allowing the use of certain XDB commands.
1232 @c For information, see the file @file{xdb_trans.html}, which is usually
1233 @c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX
1234 @c systems.
1235
1236 @item -interpreter @var{interp}
1237 @cindex @code{--interpreter}
1238 Use the interpreter @var{interp} for interface with the controlling
1239 program or device.  This option is meant to be set by programs which
1240 communicate with @value{GDBN} using it as a back end.
1241 @xref{Interpreters, , Command Interpreters}.
1242
1243 @samp{--interpreter=mi} (or @samp{--interpreter=mi2}) causes
1244 @value{GDBN} to use the @dfn{@sc{gdb/mi} interface} (@pxref{GDB/MI, ,
1245 The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0.  The
1246 previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
1247 selected with @samp{--interpreter=mi1}, is deprecated.  Earlier
1248 @sc{gdb/mi} interfaces are no longer supported.
1249
1250 @item -write
1251 @cindex @code{--write}
1252 Open the executable and core files for both reading and writing.  This
1253 is equivalent to the @samp{set write on} command inside @value{GDBN}
1254 (@pxref{Patching}).
1255
1256 @item -statistics
1257 @cindex @code{--statistics}
1258 This option causes @value{GDBN} to print statistics about time and
1259 memory usage after it completes each command and returns to the prompt.
1260
1261 @item -version
1262 @cindex @code{--version}
1263 This option causes @value{GDBN} to print its version number and
1264 no-warranty blurb, and exit.
1265
1266 @end table
1267
1268 @node Startup
1269 @subsection What @value{GDBN} Does During Startup
1270 @cindex @value{GDBN} startup
1271
1272 Here's the description of what @value{GDBN} does during session startup:
1273
1274 @enumerate
1275 @item
1276 Sets up the command interpreter as specified by the command line
1277 (@pxref{Mode Options, interpreter}).
1278
1279 @item
1280 @cindex init file
1281 Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
1282 used when building @value{GDBN}; @pxref{System-wide configuration,
1283  ,System-wide configuration and settings}) and executes all the commands in
1284 that file.
1285
1286 @anchor{Home Directory Init File}
1287 @item
1288 Reads the init file (if any) in your home directory@footnote{On
1289 DOS/Windows systems, the home directory is the one pointed to by the
1290 @code{HOME} environment variable.} and executes all the commands in
1291 that file.
1292
1293 @anchor{Option -init-eval-command}
1294 @item
1295 Executes commands and command files specified by the @samp{-iex} and
1296 @samp{-ix} options in their specified order.  Usually you should use the
1297 @samp{-ex} and @samp{-x} options instead, but this way you can apply
1298 settings before @value{GDBN} init files get executed and before inferior
1299 gets loaded.
1300
1301 @item
1302 Processes command line options and operands.
1303
1304 @anchor{Init File in the Current Directory during Startup}
1305 @item
1306 Reads and executes the commands from init file (if any) in the current
1307 working directory as long as @samp{set auto-load local-gdbinit} is set to
1308 @samp{on} (@pxref{Init File in the Current Directory}).
1309 This is only done if the current directory is
1310 different from your home directory.  Thus, you can have more than one
1311 init file, one generic in your home directory, and another, specific
1312 to the program you are debugging, in the directory where you invoke
1313 @value{GDBN}.
1314
1315 @item
1316 If the command line specified a program to debug, or a process to
1317 attach to, or a core file, @value{GDBN} loads any auto-loaded
1318 scripts provided for the program or for its loaded shared libraries.
1319 @xref{Auto-loading}.
1320
1321 If you wish to disable the auto-loading during startup,
1322 you must do something like the following:
1323
1324 @smallexample
1325 $ gdb -iex "set auto-load python-scripts off" myprogram
1326 @end smallexample
1327
1328 Option @samp{-ex} does not work because the auto-loading is then turned
1329 off too late.
1330
1331 @item
1332 Executes commands and command files specified by the @samp{-ex} and
1333 @samp{-x} options in their specified order.  @xref{Command Files}, for
1334 more details about @value{GDBN} command files.
1335
1336 @item
1337 Reads the command history recorded in the @dfn{history file}.
1338 @xref{Command History}, for more details about the command history and the
1339 files where @value{GDBN} records it.
1340 @end enumerate
1341
1342 Init files use the same syntax as @dfn{command files} (@pxref{Command
1343 Files}) and are processed by @value{GDBN} in the same way.  The init
1344 file in your home directory can set options (such as @samp{set
1345 complaints}) that affect subsequent processing of command line options
1346 and operands.  Init files are not executed if you use the @samp{-nx}
1347 option (@pxref{Mode Options, ,Choosing Modes}).
1348
1349 To display the list of init files loaded by gdb at startup, you
1350 can use @kbd{gdb --help}.
1351
1352 @cindex init file name
1353 @cindex @file{.gdbinit}
1354 @cindex @file{gdb.ini}
1355 The @value{GDBN} init files are normally called @file{.gdbinit}.
1356 The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
1357 the limitations of file names imposed by DOS filesystems.  The Windows
1358 port of @value{GDBN} uses the standard name, but if it finds a
1359 @file{gdb.ini} file in your home directory, it warns you about that
1360 and suggests to rename the file to the standard name.
1361
1362
1363 @node Quitting GDB
1364 @section Quitting @value{GDBN}
1365 @cindex exiting @value{GDBN}
1366 @cindex leaving @value{GDBN}
1367
1368 @table @code
1369 @kindex quit @r{[}@var{expression}@r{]}
1370 @kindex q @r{(@code{quit})}
1371 @item quit @r{[}@var{expression}@r{]}
1372 @itemx q
1373 To exit @value{GDBN}, use the @code{quit} command (abbreviated
1374 @code{q}), or type an end-of-file character (usually @kbd{Ctrl-d}).  If you
1375 do not supply @var{expression}, @value{GDBN} will terminate normally;
1376 otherwise it will terminate using the result of @var{expression} as the
1377 error code.
1378 @end table
1379
1380 @cindex interrupt
1381 An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
1382 terminates the action of any @value{GDBN} command that is in progress and
1383 returns to @value{GDBN} command level.  It is safe to type the interrupt
1384 character at any time because @value{GDBN} does not allow it to take effect
1385 until a time when it is safe.
1386
1387 If you have been using @value{GDBN} to control an attached process or
1388 device, you can release it with the @code{detach} command
1389 (@pxref{Attach, ,Debugging an Already-running Process}).
1390
1391 @node Shell Commands
1392 @section Shell Commands
1393
1394 If you need to execute occasional shell commands during your
1395 debugging session, there is no need to leave or suspend @value{GDBN}; you can
1396 just use the @code{shell} command.
1397
1398 @table @code
1399 @kindex shell
1400 @kindex !
1401 @cindex shell escape
1402 @item shell @var{command-string}
1403 @itemx !@var{command-string}
1404 Invoke a standard shell to execute @var{command-string}.
1405 Note that no space is needed between @code{!} and @var{command-string}.
1406 If it exists, the environment variable @code{SHELL} determines which
1407 shell to run.  Otherwise @value{GDBN} uses the default shell
1408 (@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.).
1409 @end table
1410
1411 The utility @code{make} is often needed in development environments.
1412 You do not have to use the @code{shell} command for this purpose in
1413 @value{GDBN}:
1414
1415 @table @code
1416 @kindex make
1417 @cindex calling make
1418 @item make @var{make-args}
1419 Execute the @code{make} program with the specified
1420 arguments.  This is equivalent to @samp{shell make @var{make-args}}.
1421 @end table
1422
1423 @node Logging Output
1424 @section Logging Output
1425 @cindex logging @value{GDBN} output
1426 @cindex save @value{GDBN} output to a file
1427
1428 You may want to save the output of @value{GDBN} commands to a file.
1429 There are several commands to control @value{GDBN}'s logging.
1430
1431 @table @code
1432 @kindex set logging
1433 @item set logging on
1434 Enable logging.
1435 @item set logging off
1436 Disable logging.
1437 @cindex logging file name
1438 @item set logging file @var{file}
1439 Change the name of the current logfile.  The default logfile is @file{gdb.txt}.
1440 @item set logging overwrite [on|off]
1441 By default, @value{GDBN} will append to the logfile.  Set @code{overwrite} if
1442 you want @code{set logging on} to overwrite the logfile instead.
1443 @item set logging redirect [on|off]
1444 By default, @value{GDBN} output will go to both the terminal and the logfile.
1445 Set @code{redirect} if you want output to go only to the log file.
1446 @kindex show logging
1447 @item show logging
1448 Show the current values of the logging settings.
1449 @end table
1450
1451 @node Commands
1452 @chapter @value{GDBN} Commands
1453
1454 You can abbreviate a @value{GDBN} command to the first few letters of the command
1455 name, if that abbreviation is unambiguous; and you can repeat certain
1456 @value{GDBN} commands by typing just @key{RET}.  You can also use the @key{TAB}
1457 key to get @value{GDBN} to fill out the rest of a word in a command (or to
1458 show you the alternatives available, if there is more than one possibility).
1459
1460 @menu
1461 * Command Syntax::              How to give commands to @value{GDBN}
1462 * Completion::                  Command completion
1463 * Help::                        How to ask @value{GDBN} for help
1464 @end menu
1465
1466 @node Command Syntax
1467 @section Command Syntax
1468
1469 A @value{GDBN} command is a single line of input.  There is no limit on
1470 how long it can be.  It starts with a command name, which is followed by
1471 arguments whose meaning depends on the command name.  For example, the
1472 command @code{step} accepts an argument which is the number of times to
1473 step, as in @samp{step 5}.  You can also use the @code{step} command
1474 with no arguments.  Some commands do not allow any arguments.
1475
1476 @cindex abbreviation
1477 @value{GDBN} command names may always be truncated if that abbreviation is
1478 unambiguous.  Other possible command abbreviations are listed in the
1479 documentation for individual commands.  In some cases, even ambiguous
1480 abbreviations are allowed; for example, @code{s} is specially defined as
1481 equivalent to @code{step} even though there are other commands whose
1482 names start with @code{s}.  You can test abbreviations by using them as
1483 arguments to the @code{help} command.
1484
1485 @cindex repeating commands
1486 @kindex RET @r{(repeat last command)}
1487 A blank line as input to @value{GDBN} (typing just @key{RET}) means to
1488 repeat the previous command.  Certain commands (for example, @code{run})
1489 will not repeat this way; these are commands whose unintentional
1490 repetition might cause trouble and which you are unlikely to want to
1491 repeat.  User-defined commands can disable this feature; see
1492 @ref{Define, dont-repeat}.
1493
1494 The @code{list} and @code{x} commands, when you repeat them with
1495 @key{RET}, construct new arguments rather than repeating
1496 exactly as typed.  This permits easy scanning of source or memory.
1497
1498 @value{GDBN} can also use @key{RET} in another way: to partition lengthy
1499 output, in a way similar to the common utility @code{more}
1500 (@pxref{Screen Size,,Screen Size}).  Since it is easy to press one
1501 @key{RET} too many in this situation, @value{GDBN} disables command
1502 repetition after any command that generates this sort of display.
1503
1504 @kindex # @r{(a comment)}
1505 @cindex comment
1506 Any text from a @kbd{#} to the end of the line is a comment; it does
1507 nothing.  This is useful mainly in command files (@pxref{Command
1508 Files,,Command Files}).
1509
1510 @cindex repeating command sequences
1511 @kindex Ctrl-o @r{(operate-and-get-next)}
1512 The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
1513 commands.  This command accepts the current line, like @key{RET}, and
1514 then fetches the next line relative to the current line from the history
1515 for editing.
1516
1517 @node Completion
1518 @section Command Completion
1519
1520 @cindex completion
1521 @cindex word completion
1522 @value{GDBN} can fill in the rest of a word in a command for you, if there is
1523 only one possibility; it can also show you what the valid possibilities
1524 are for the next word in a command, at any time.  This works for @value{GDBN}
1525 commands, @value{GDBN} subcommands, and the names of symbols in your program.
1526
1527 Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1528 of a word.  If there is only one possibility, @value{GDBN} fills in the
1529 word, and waits for you to finish the command (or press @key{RET} to
1530 enter it).  For example, if you type
1531
1532 @c FIXME "@key" does not distinguish its argument sufficiently to permit
1533 @c complete accuracy in these examples; space introduced for clarity.
1534 @c If texinfo enhancements make it unnecessary, it would be nice to
1535 @c replace " @key" by "@key" in the following...
1536 @smallexample
1537 (@value{GDBP}) info bre @key{TAB}
1538 @end smallexample
1539
1540 @noindent
1541 @value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is
1542 the only @code{info} subcommand beginning with @samp{bre}:
1543
1544 @smallexample
1545 (@value{GDBP}) info breakpoints
1546 @end smallexample
1547
1548 @noindent
1549 You can either press @key{RET} at this point, to run the @code{info
1550 breakpoints} command, or backspace and enter something else, if
1551 @samp{breakpoints} does not look like the command you expected.  (If you
1552 were sure you wanted @code{info breakpoints} in the first place, you
1553 might as well just type @key{RET} immediately after @samp{info bre},
1554 to exploit command abbreviations rather than command completion).
1555
1556 If there is more than one possibility for the next word when you press
1557 @key{TAB}, @value{GDBN} sounds a bell.  You can either supply more
1558 characters and try again, or just press @key{TAB} a second time;
1559 @value{GDBN} displays all the possible completions for that word.  For
1560 example, you might want to set a breakpoint on a subroutine whose name
1561 begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1562 just sounds the bell.  Typing @key{TAB} again displays all the
1563 function names in your program that begin with those characters, for
1564 example:
1565
1566 @smallexample
1567 (@value{GDBP}) b make_ @key{TAB}
1568 @exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
1569 make_a_section_from_file     make_environ
1570 make_abs_section             make_function_type
1571 make_blockvector             make_pointer_type
1572 make_cleanup                 make_reference_type
1573 make_command                 make_symbol_completion_list
1574 (@value{GDBP}) b make_
1575 @end smallexample
1576
1577 @noindent
1578 After displaying the available possibilities, @value{GDBN} copies your
1579 partial input (@samp{b make_} in the example) so you can finish the
1580 command.
1581
1582 If you just want to see the list of alternatives in the first place, you
1583 can press @kbd{M-?} rather than pressing @key{TAB} twice.  @kbd{M-?}
1584 means @kbd{@key{META} ?}.  You can type this either by holding down a
1585 key designated as the @key{META} shift on your keyboard (if there is
1586 one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
1587
1588 @cindex quotes in commands
1589 @cindex completion of quoted strings
1590 Sometimes the string you need, while logically a ``word'', may contain
1591 parentheses or other characters that @value{GDBN} normally excludes from
1592 its notion of a word.  To permit word completion to work in this
1593 situation, you may enclose words in @code{'} (single quote marks) in
1594 @value{GDBN} commands.
1595
1596 The most likely situation where you might need this is in typing the
1597 name of a C@t{++} function.  This is because C@t{++} allows function
1598 overloading (multiple definitions of the same function, distinguished
1599 by argument type).  For example, when you want to set a breakpoint you
1600 may need to distinguish whether you mean the version of @code{name}
1601 that takes an @code{int} parameter, @code{name(int)}, or the version
1602 that takes a @code{float} parameter, @code{name(float)}.  To use the
1603 word-completion facilities in this situation, type a single quote
1604 @code{'} at the beginning of the function name.  This alerts
1605 @value{GDBN} that it may need to consider more information than usual
1606 when you press @key{TAB} or @kbd{M-?} to request word completion:
1607
1608 @smallexample
1609 (@value{GDBP}) b 'bubble( @kbd{M-?}
1610 bubble(double,double)    bubble(int,int)
1611 (@value{GDBP}) b 'bubble(
1612 @end smallexample
1613
1614 In some cases, @value{GDBN} can tell that completing a name requires using
1615 quotes.  When this happens, @value{GDBN} inserts the quote for you (while
1616 completing as much as it can) if you do not type the quote in the first
1617 place:
1618
1619 @smallexample
1620 (@value{GDBP}) b bub @key{TAB}
1621 @exdent @value{GDBN} alters your input line to the following, and rings a bell:
1622 (@value{GDBP}) b 'bubble(
1623 @end smallexample
1624
1625 @noindent
1626 In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1627 you have not yet started typing the argument list when you ask for
1628 completion on an overloaded symbol.
1629
1630 For more information about overloaded functions, see @ref{C Plus Plus
1631 Expressions, ,C@t{++} Expressions}.  You can use the command @code{set
1632 overload-resolution off} to disable overload resolution;
1633 see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}.
1634
1635 @cindex completion of structure field names
1636 @cindex structure field name completion
1637 @cindex completion of union field names
1638 @cindex union field name completion
1639 When completing in an expression which looks up a field in a
1640 structure, @value{GDBN} also tries@footnote{The completer can be
1641 confused by certain kinds of invalid expressions.  Also, it only
1642 examines the static type of the expression, not the dynamic type.} to
1643 limit completions to the field names available in the type of the
1644 left-hand-side:
1645
1646 @smallexample
1647 (@value{GDBP}) p gdb_stdout.@kbd{M-?}
1648 magic                to_fputs             to_rewind
1649 to_data              to_isatty            to_write
1650 to_delete            to_put               to_write_async_safe
1651 to_flush             to_read
1652 @end smallexample
1653
1654 @noindent
1655 This is because the @code{gdb_stdout} is a variable of the type
1656 @code{struct ui_file} that is defined in @value{GDBN} sources as
1657 follows:
1658
1659 @smallexample
1660 struct ui_file
1661 @{
1662    int *magic;
1663    ui_file_flush_ftype *to_flush;
1664    ui_file_write_ftype *to_write;
1665    ui_file_write_async_safe_ftype *to_write_async_safe;
1666    ui_file_fputs_ftype *to_fputs;
1667    ui_file_read_ftype *to_read;
1668    ui_file_delete_ftype *to_delete;
1669    ui_file_isatty_ftype *to_isatty;
1670    ui_file_rewind_ftype *to_rewind;
1671    ui_file_put_ftype *to_put;
1672    void *to_data;
1673 @}
1674 @end smallexample
1675
1676
1677 @node Help
1678 @section Getting Help
1679 @cindex online documentation
1680 @kindex help
1681
1682 You can always ask @value{GDBN} itself for information on its commands,
1683 using the command @code{help}.
1684
1685 @table @code
1686 @kindex h @r{(@code{help})}
1687 @item help
1688 @itemx h
1689 You can use @code{help} (abbreviated @code{h}) with no arguments to
1690 display a short list of named classes of commands:
1691
1692 @smallexample
1693 (@value{GDBP}) help
1694 List of classes of commands:
1695
1696 aliases -- Aliases of other commands
1697 breakpoints -- Making program stop at certain points
1698 data -- Examining data
1699 files -- Specifying and examining files
1700 internals -- Maintenance commands
1701 obscure -- Obscure features
1702 running -- Running the program
1703 stack -- Examining the stack
1704 status -- Status inquiries
1705 support -- Support facilities
1706 tracepoints -- Tracing of program execution without
1707                stopping the program
1708 user-defined -- User-defined commands
1709
1710 Type "help" followed by a class name for a list of
1711 commands in that class.
1712 Type "help" followed by command name for full
1713 documentation.
1714 Command name abbreviations are allowed if unambiguous.
1715 (@value{GDBP})
1716 @end smallexample
1717 @c the above line break eliminates huge line overfull...
1718
1719 @item help @var{class}
1720 Using one of the general help classes as an argument, you can get a
1721 list of the individual commands in that class.  For example, here is the
1722 help display for the class @code{status}:
1723
1724 @smallexample
1725 (@value{GDBP}) help status
1726 Status inquiries.
1727
1728 List of commands:
1729
1730 @c Line break in "show" line falsifies real output, but needed
1731 @c to fit in smallbook page size.
1732 info -- Generic command for showing things
1733         about the program being debugged
1734 show -- Generic command for showing things
1735         about the debugger
1736
1737 Type "help" followed by command name for full
1738 documentation.
1739 Command name abbreviations are allowed if unambiguous.
1740 (@value{GDBP})
1741 @end smallexample
1742
1743 @item help @var{command}
1744 With a command name as @code{help} argument, @value{GDBN} displays a
1745 short paragraph on how to use that command.
1746
1747 @kindex apropos
1748 @item apropos @var{args}
1749 The @code{apropos} command searches through all of the @value{GDBN}
1750 commands, and their documentation, for the regular expression specified in
1751 @var{args}.  It prints out all matches found.  For example:
1752
1753 @smallexample
1754 apropos alias
1755 @end smallexample
1756
1757 @noindent
1758 results in:
1759
1760 @smallexample
1761 @c @group
1762 alias -- Define a new command that is an alias of an existing command
1763 aliases -- Aliases of other commands
1764 d -- Delete some breakpoints or auto-display expressions
1765 del -- Delete some breakpoints or auto-display expressions
1766 delete -- Delete some breakpoints or auto-display expressions
1767 @c @end group
1768 @end smallexample
1769
1770 @kindex complete
1771 @item complete @var{args}
1772 The @code{complete @var{args}} command lists all the possible completions
1773 for the beginning of a command.  Use @var{args} to specify the beginning of the
1774 command you want completed.  For example:
1775
1776 @smallexample
1777 complete i
1778 @end smallexample
1779
1780 @noindent results in:
1781
1782 @smallexample
1783 @group
1784 if
1785 ignore
1786 info
1787 inspect
1788 @end group
1789 @end smallexample
1790
1791 @noindent This is intended for use by @sc{gnu} Emacs.
1792 @end table
1793
1794 In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1795 and @code{show} to inquire about the state of your program, or the state
1796 of @value{GDBN} itself.  Each command supports many topics of inquiry; this
1797 manual introduces each of them in the appropriate context.  The listings
1798 under @code{info} and under @code{show} in the Command, Variable, and
1799 Function Index point to all the sub-commands.  @xref{Command and Variable
1800 Index}.
1801
1802 @c @group
1803 @table @code
1804 @kindex info
1805 @kindex i @r{(@code{info})}
1806 @item info
1807 This command (abbreviated @code{i}) is for describing the state of your
1808 program.  For example, you can show the arguments passed to a function
1809 with @code{info args}, list the registers currently in use with @code{info
1810 registers}, or list the breakpoints you have set with @code{info breakpoints}.
1811 You can get a complete list of the @code{info} sub-commands with
1812 @w{@code{help info}}.
1813
1814 @kindex set
1815 @item set
1816 You can assign the result of an expression to an environment variable with
1817 @code{set}.  For example, you can set the @value{GDBN} prompt to a $-sign with
1818 @code{set prompt $}.
1819
1820 @kindex show
1821 @item show
1822 In contrast to @code{info}, @code{show} is for describing the state of
1823 @value{GDBN} itself.
1824 You can change most of the things you can @code{show}, by using the
1825 related command @code{set}; for example, you can control what number
1826 system is used for displays with @code{set radix}, or simply inquire
1827 which is currently in use with @code{show radix}.
1828
1829 @kindex info set
1830 To display all the settable parameters and their current
1831 values, you can use @code{show} with no arguments; you may also use
1832 @code{info set}.  Both commands produce the same display.
1833 @c FIXME: "info set" violates the rule that "info" is for state of
1834 @c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
1835 @c FIXME...or change desc of rule---eg "state of prog and debugging session"?
1836 @end table
1837 @c @end group
1838
1839 Here are three miscellaneous @code{show} subcommands, all of which are
1840 exceptional in lacking corresponding @code{set} commands:
1841
1842 @table @code
1843 @kindex show version
1844 @cindex @value{GDBN} version number
1845 @item show version
1846 Show what version of @value{GDBN} is running.  You should include this
1847 information in @value{GDBN} bug-reports.  If multiple versions of
1848 @value{GDBN} are in use at your site, you may need to determine which
1849 version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1850 commands are introduced, and old ones may wither away.  Also, many
1851 system vendors ship variant versions of @value{GDBN}, and there are
1852 variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
1853 The version number is the same as the one announced when you start
1854 @value{GDBN}.
1855
1856 @kindex show copying
1857 @kindex info copying
1858 @cindex display @value{GDBN} copyright
1859 @item show copying
1860 @itemx info copying
1861 Display information about permission for copying @value{GDBN}.
1862
1863 @kindex show warranty
1864 @kindex info warranty
1865 @item show warranty
1866 @itemx info warranty
1867 Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
1868 if your version of @value{GDBN} comes with one.
1869
1870 @end table
1871
1872 @node Running
1873 @chapter Running Programs Under @value{GDBN}
1874
1875 When you run a program under @value{GDBN}, you must first generate
1876 debugging information when you compile it.
1877
1878 You may start @value{GDBN} with its arguments, if any, in an environment
1879 of your choice.  If you are doing native debugging, you may redirect
1880 your program's input and output, debug an already running process, or
1881 kill a child process.
1882
1883 @menu
1884 * Compilation::                 Compiling for debugging
1885 * Starting::                    Starting your program
1886 * Arguments::                   Your program's arguments
1887 * Environment::                 Your program's environment
1888
1889 * Working Directory::           Your program's working directory
1890 * Input/Output::                Your program's input and output
1891 * Attach::                      Debugging an already-running process
1892 * Kill Process::                Killing the child process
1893
1894 * Inferiors and Programs::      Debugging multiple inferiors and programs
1895 * Threads::                     Debugging programs with multiple threads
1896 * Forks::                       Debugging forks
1897 * Checkpoint/Restart::          Setting a @emph{bookmark} to return to later
1898 @end menu
1899
1900 @node Compilation
1901 @section Compiling for Debugging
1902
1903 In order to debug a program effectively, you need to generate
1904 debugging information when you compile it.  This debugging information
1905 is stored in the object file; it describes the data type of each
1906 variable or function and the correspondence between source line numbers
1907 and addresses in the executable code.
1908
1909 To request debugging information, specify the @samp{-g} option when you run
1910 the compiler.
1911
1912 Programs that are to be shipped to your customers are compiled with
1913 optimizations, using the @samp{-O} compiler option.  However, some
1914 compilers are unable to handle the @samp{-g} and @samp{-O} options
1915 together.  Using those compilers, you cannot generate optimized
1916 executables containing debugging information.
1917
1918 @value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
1919 without @samp{-O}, making it possible to debug optimized code.  We
1920 recommend that you @emph{always} use @samp{-g} whenever you compile a
1921 program.  You may think your program is correct, but there is no sense
1922 in pushing your luck.  For more information, see @ref{Optimized Code}.
1923
1924 Older versions of the @sc{gnu} C compiler permitted a variant option
1925 @w{@samp{-gg}} for debugging information.  @value{GDBN} no longer supports this
1926 format; if your @sc{gnu} C compiler has this option, do not use it.
1927
1928 @value{GDBN} knows about preprocessor macros and can show you their
1929 expansion (@pxref{Macros}).  Most compilers do not include information
1930 about preprocessor macros in the debugging information if you specify
1931 the @option{-g} flag alone.  Version 3.1 and later of @value{NGCC},
1932 the @sc{gnu} C compiler, provides macro information if you are using
1933 the DWARF debugging format, and specify the option @option{-g3}.
1934
1935 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
1936 gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more
1937 information on @value{NGCC} options affecting debug information.
1938
1939 You will have the best debugging experience if you use the latest
1940 version of the DWARF debugging format that your compiler supports.
1941 DWARF is currently the most expressive and best supported debugging
1942 format in @value{GDBN}.
1943
1944 @need 2000
1945 @node Starting
1946 @section Starting your Program
1947 @cindex starting
1948 @cindex running
1949
1950 @table @code
1951 @kindex run
1952 @kindex r @r{(@code{run})}
1953 @item run
1954 @itemx r
1955 Use the @code{run} command to start your program under @value{GDBN}.
1956 You must first specify the program name (except on VxWorks) with an
1957 argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of
1958 @value{GDBN}}), or by using the @code{file} or @code{exec-file} command
1959 (@pxref{Files, ,Commands to Specify Files}).
1960
1961 @end table
1962
1963 If you are running your program in an execution environment that
1964 supports processes, @code{run} creates an inferior process and makes
1965 that process run your program.  In some environments without processes,
1966 @code{run} jumps to the start of your program.  Other targets,
1967 like @samp{remote}, are always running.  If you get an error
1968 message like this one:
1969
1970 @smallexample
1971 The "remote" target does not support "run".
1972 Try "help target" or "continue".
1973 @end smallexample
1974
1975 @noindent
1976 then use @code{continue} to run your program.  You may need @code{load}
1977 first (@pxref{load}).
1978
1979 The execution of a program is affected by certain information it
1980 receives from its superior.  @value{GDBN} provides ways to specify this
1981 information, which you must do @emph{before} starting your program.  (You
1982 can change it after starting your program, but such changes only affect
1983 your program the next time you start it.)  This information may be
1984 divided into four categories:
1985
1986 @table @asis
1987 @item The @emph{arguments.}
1988 Specify the arguments to give your program as the arguments of the
1989 @code{run} command.  If a shell is available on your target, the shell
1990 is used to pass the arguments, so that you may use normal conventions
1991 (such as wildcard expansion or variable substitution) in describing
1992 the arguments.
1993 In Unix systems, you can control which shell is used with the
1994 @code{SHELL} environment variable.
1995 @xref{Arguments, ,Your Program's Arguments}.
1996
1997 @item The @emph{environment.}
1998 Your program normally inherits its environment from @value{GDBN}, but you can
1999 use the @value{GDBN} commands @code{set environment} and @code{unset
2000 environment} to change parts of the environment that affect
2001 your program.  @xref{Environment, ,Your Program's Environment}.
2002
2003 @item The @emph{working directory.}
2004 Your program inherits its working directory from @value{GDBN}.  You can set
2005 the @value{GDBN} working directory with the @code{cd} command in @value{GDBN}.
2006 @xref{Working Directory, ,Your Program's Working Directory}.
2007
2008 @item The @emph{standard input and output.}
2009 Your program normally uses the same device for standard input and
2010 standard output as @value{GDBN} is using.  You can redirect input and output
2011 in the @code{run} command line, or you can use the @code{tty} command to
2012 set a different device for your program.
2013 @xref{Input/Output, ,Your Program's Input and Output}.
2014
2015 @cindex pipes
2016 @emph{Warning:} While input and output redirection work, you cannot use
2017 pipes to pass the output of the program you are debugging to another
2018 program; if you attempt this, @value{GDBN} is likely to wind up debugging the
2019 wrong program.
2020 @end table
2021
2022 When you issue the @code{run} command, your program begins to execute
2023 immediately.  @xref{Stopping, ,Stopping and Continuing}, for discussion
2024 of how to arrange for your program to stop.  Once your program has
2025 stopped, you may call functions in your program, using the @code{print}
2026 or @code{call} commands.  @xref{Data, ,Examining Data}.
2027
2028 If the modification time of your symbol file has changed since the last
2029 time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
2030 table, and reads it again.  When it does this, @value{GDBN} tries to retain
2031 your current breakpoints.
2032
2033 @table @code
2034 @kindex start
2035 @item start
2036 @cindex run to main procedure
2037 The name of the main procedure can vary from language to language.
2038 With C or C@t{++}, the main procedure name is always @code{main}, but
2039 other languages such as Ada do not require a specific name for their
2040 main procedure.  The debugger provides a convenient way to start the
2041 execution of the program and to stop at the beginning of the main
2042 procedure, depending on the language used.
2043
2044 The @samp{start} command does the equivalent of setting a temporary
2045 breakpoint at the beginning of the main procedure and then invoking
2046 the @samp{run} command.
2047
2048 @cindex elaboration phase
2049 Some programs contain an @dfn{elaboration} phase where some startup code is
2050 executed before the main procedure is called.  This depends on the
2051 languages used to write your program.  In C@t{++}, for instance,
2052 constructors for static and global objects are executed before
2053 @code{main} is called.  It is therefore possible that the debugger stops
2054 before reaching the main procedure.  However, the temporary breakpoint
2055 will remain to halt execution.
2056
2057 Specify the arguments to give to your program as arguments to the
2058 @samp{start} command.  These arguments will be given verbatim to the
2059 underlying @samp{run} command.  Note that the same arguments will be
2060 reused if no argument is provided during subsequent calls to
2061 @samp{start} or @samp{run}.
2062
2063 It is sometimes necessary to debug the program during elaboration.  In
2064 these cases, using the @code{start} command would stop the execution of
2065 your program too late, as the program would have already completed the
2066 elaboration phase.  Under these circumstances, insert breakpoints in your
2067 elaboration code before running your program.
2068
2069 @kindex set exec-wrapper
2070 @item set exec-wrapper @var{wrapper}
2071 @itemx show exec-wrapper
2072 @itemx unset exec-wrapper
2073 When @samp{exec-wrapper} is set, the specified wrapper is used to
2074 launch programs for debugging.  @value{GDBN} starts your program
2075 with a shell command of the form @kbd{exec @var{wrapper}
2076 @var{program}}.  Quoting is added to @var{program} and its
2077 arguments, but not to @var{wrapper}, so you should add quotes if
2078 appropriate for your shell.  The wrapper runs until it executes
2079 your program, and then @value{GDBN} takes control.
2080
2081 You can use any program that eventually calls @code{execve} with
2082 its arguments as a wrapper.  Several standard Unix utilities do
2083 this, e.g.@: @code{env} and @code{nohup}.  Any Unix shell script ending
2084 with @code{exec "$@@"} will also work.
2085
2086 For example, you can use @code{env} to pass an environment variable to
2087 the debugged program, without setting the variable in your shell's
2088 environment:
2089
2090 @smallexample
2091 (@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
2092 (@value{GDBP}) run
2093 @end smallexample
2094
2095 This command is available when debugging locally on most targets, excluding
2096 @sc{djgpp}, Cygwin, MS Windows, and QNX Neutrino.
2097
2098 @kindex set disable-randomization
2099 @item set disable-randomization
2100 @itemx set disable-randomization on
2101 This option (enabled by default in @value{GDBN}) will turn off the native
2102 randomization of the virtual address space of the started program.  This option
2103 is useful for multiple debugging sessions to make the execution better
2104 reproducible and memory addresses reusable across debugging sessions.
2105
2106 This feature is implemented only on certain targets, including @sc{gnu}/Linux.
2107 On @sc{gnu}/Linux you can get the same behavior using
2108
2109 @smallexample
2110 (@value{GDBP}) set exec-wrapper setarch `uname -m` -R
2111 @end smallexample
2112
2113 @item set disable-randomization off
2114 Leave the behavior of the started executable unchanged.  Some bugs rear their
2115 ugly heads only when the program is loaded at certain addresses.  If your bug
2116 disappears when you run the program under @value{GDBN}, that might be because
2117 @value{GDBN} by default disables the address randomization on platforms, such
2118 as @sc{gnu}/Linux, which do that for stand-alone programs.  Use @kbd{set
2119 disable-randomization off} to try to reproduce such elusive bugs.
2120
2121 On targets where it is available, virtual address space randomization
2122 protects the programs against certain kinds of security attacks.  In these
2123 cases the attacker needs to know the exact location of a concrete executable
2124 code.  Randomizing its location makes it impossible to inject jumps misusing
2125 a code at its expected addresses.
2126
2127 Prelinking shared libraries provides a startup performance advantage but it
2128 makes addresses in these libraries predictable for privileged processes by
2129 having just unprivileged access at the target system.  Reading the shared
2130 library binary gives enough information for assembling the malicious code
2131 misusing it.  Still even a prelinked shared library can get loaded at a new
2132 random address just requiring the regular relocation process during the
2133 startup.  Shared libraries not already prelinked are always loaded at
2134 a randomly chosen address.
2135
2136 Position independent executables (PIE) contain position independent code
2137 similar to the shared libraries and therefore such executables get loaded at
2138 a randomly chosen address upon startup.  PIE executables always load even
2139 already prelinked shared libraries at a random address.  You can build such
2140 executable using @command{gcc -fPIE -pie}.
2141
2142 Heap (malloc storage), stack and custom mmap areas are always placed randomly
2143 (as long as the randomization is enabled).
2144
2145 @item show disable-randomization
2146 Show the current setting of the explicit disable of the native randomization of
2147 the virtual address space of the started program.
2148
2149 @end table
2150
2151 @node Arguments
2152 @section Your Program's Arguments
2153
2154 @cindex arguments (to your program)
2155 The arguments to your program can be specified by the arguments of the
2156 @code{run} command.
2157 They are passed to a shell, which expands wildcard characters and
2158 performs redirection of I/O, and thence to your program.  Your
2159 @code{SHELL} environment variable (if it exists) specifies what shell
2160 @value{GDBN} uses.  If you do not define @code{SHELL}, @value{GDBN} uses
2161 the default shell (@file{/bin/sh} on Unix).
2162
2163 On non-Unix systems, the program is usually invoked directly by
2164 @value{GDBN}, which emulates I/O redirection via the appropriate system
2165 calls, and the wildcard characters are expanded by the startup code of
2166 the program, not by the shell.
2167
2168 @code{run} with no arguments uses the same arguments used by the previous
2169 @code{run}, or those set by the @code{set args} command.
2170
2171 @table @code
2172 @kindex set args
2173 @item set args
2174 Specify the arguments to be used the next time your program is run.  If
2175 @code{set args} has no arguments, @code{run} executes your program
2176 with no arguments.  Once you have run your program with arguments,
2177 using @code{set args} before the next @code{run} is the only way to run
2178 it again without arguments.
2179
2180 @kindex show args
2181 @item show args
2182 Show the arguments to give your program when it is started.
2183 @end table
2184
2185 @node Environment
2186 @section Your Program's Environment
2187
2188 @cindex environment (of your program)
2189 The @dfn{environment} consists of a set of environment variables and
2190 their values.  Environment variables conventionally record such things as
2191 your user name, your home directory, your terminal type, and your search
2192 path for programs to run.  Usually you set up environment variables with
2193 the shell and they are inherited by all the other programs you run.  When
2194 debugging, it can be useful to try running your program with a modified
2195 environment without having to start @value{GDBN} over again.
2196
2197 @table @code
2198 @kindex path
2199 @item path @var{directory}
2200 Add @var{directory} to the front of the @code{PATH} environment variable
2201 (the search path for executables) that will be passed to your program.
2202 The value of @code{PATH} used by @value{GDBN} does not change.
2203 You may specify several directory names, separated by whitespace or by a
2204 system-dependent separator character (@samp{:} on Unix, @samp{;} on
2205 MS-DOS and MS-Windows).  If @var{directory} is already in the path, it
2206 is moved to the front, so it is searched sooner.
2207
2208 You can use the string @samp{$cwd} to refer to whatever is the current
2209 working directory at the time @value{GDBN} searches the path.  If you
2210 use @samp{.} instead, it refers to the directory where you executed the
2211 @code{path} command.  @value{GDBN} replaces @samp{.} in the
2212 @var{directory} argument (with the current path) before adding
2213 @var{directory} to the search path.
2214 @c 'path' is explicitly nonrepeatable, but RMS points out it is silly to
2215 @c document that, since repeating it would be a no-op.
2216
2217 @kindex show paths
2218 @item show paths
2219 Display the list of search paths for executables (the @code{PATH}
2220 environment variable).
2221
2222 @kindex show environment
2223 @item show environment @r{[}@var{varname}@r{]}
2224 Print the value of environment variable @var{varname} to be given to
2225 your program when it starts.  If you do not supply @var{varname},
2226 print the names and values of all environment variables to be given to
2227 your program.  You can abbreviate @code{environment} as @code{env}.
2228
2229 @kindex set environment
2230 @item set environment @var{varname} @r{[}=@var{value}@r{]}
2231 Set environment variable @var{varname} to @var{value}.  The value
2232 changes for your program only, not for @value{GDBN} itself.  @var{value} may
2233 be any string; the values of environment variables are just strings, and
2234 any interpretation is supplied by your program itself.  The @var{value}
2235 parameter is optional; if it is eliminated, the variable is set to a
2236 null value.
2237 @c "any string" here does not include leading, trailing
2238 @c blanks. Gnu asks: does anyone care?
2239
2240 For example, this command:
2241
2242 @smallexample
2243 set env USER = foo
2244 @end smallexample
2245
2246 @noindent
2247 tells the debugged program, when subsequently run, that its user is named
2248 @samp{foo}.  (The spaces around @samp{=} are used for clarity here; they
2249 are not actually required.)
2250
2251 @kindex unset environment
2252 @item unset environment @var{varname}
2253 Remove variable @var{varname} from the environment to be passed to your
2254 program.  This is different from @samp{set env @var{varname} =};
2255 @code{unset environment} removes the variable from the environment,
2256 rather than assigning it an empty value.
2257 @end table
2258
2259 @emph{Warning:} On Unix systems, @value{GDBN} runs your program using
2260 the shell indicated
2261 by your @code{SHELL} environment variable if it exists (or
2262 @code{/bin/sh} if not).  If your @code{SHELL} variable names a shell
2263 that runs an initialization file---such as @file{.cshrc} for C-shell, or
2264 @file{.bashrc} for BASH---any variables you set in that file affect
2265 your program.  You may wish to move setting of environment variables to
2266 files that are only run when you sign on, such as @file{.login} or
2267 @file{.profile}.
2268
2269 @node Working Directory
2270 @section Your Program's Working Directory
2271
2272 @cindex working directory (of your program)
2273 Each time you start your program with @code{run}, it inherits its
2274 working directory from the current working directory of @value{GDBN}.
2275 The @value{GDBN} working directory is initially whatever it inherited
2276 from its parent process (typically the shell), but you can specify a new
2277 working directory in @value{GDBN} with the @code{cd} command.
2278
2279 The @value{GDBN} working directory also serves as a default for the commands
2280 that specify files for @value{GDBN} to operate on.  @xref{Files, ,Commands to
2281 Specify Files}.
2282
2283 @table @code
2284 @kindex cd
2285 @cindex change working directory
2286 @item cd @r{[}@var{directory}@r{]}
2287 Set the @value{GDBN} working directory to @var{directory}.  If not
2288 given, @var{directory} uses @file{'~'}.
2289
2290 @kindex pwd
2291 @item pwd
2292 Print the @value{GDBN} working directory.
2293 @end table
2294
2295 It is generally impossible to find the current working directory of
2296 the process being debugged (since a program can change its directory
2297 during its run).  If you work on a system where @value{GDBN} is
2298 configured with the @file{/proc} support, you can use the @code{info
2299 proc} command (@pxref{SVR4 Process Information}) to find out the
2300 current working directory of the debuggee.
2301
2302 @node Input/Output
2303 @section Your Program's Input and Output
2304
2305 @cindex redirection
2306 @cindex i/o
2307 @cindex terminal
2308 By default, the program you run under @value{GDBN} does input and output to
2309 the same terminal that @value{GDBN} uses.  @value{GDBN} switches the terminal
2310 to its own terminal modes to interact with you, but it records the terminal
2311 modes your program was using and switches back to them when you continue
2312 running your program.
2313
2314 @table @code
2315 @kindex info terminal
2316 @item info terminal
2317 Displays information recorded by @value{GDBN} about the terminal modes your
2318 program is using.
2319 @end table
2320
2321 You can redirect your program's input and/or output using shell
2322 redirection with the @code{run} command.  For example,
2323
2324 @smallexample
2325 run > outfile
2326 @end smallexample
2327
2328 @noindent
2329 starts your program, diverting its output to the file @file{outfile}.
2330
2331 @kindex tty
2332 @cindex controlling terminal
2333 Another way to specify where your program should do input and output is
2334 with the @code{tty} command.  This command accepts a file name as
2335 argument, and causes this file to be the default for future @code{run}
2336 commands.  It also resets the controlling terminal for the child
2337 process, for future @code{run} commands.  For example,
2338
2339 @smallexample
2340 tty /dev/ttyb
2341 @end smallexample
2342
2343 @noindent
2344 directs that processes started with subsequent @code{run} commands
2345 default to do input and output on the terminal @file{/dev/ttyb} and have
2346 that as their controlling terminal.
2347
2348 An explicit redirection in @code{run} overrides the @code{tty} command's
2349 effect on the input/output device, but not its effect on the controlling
2350 terminal.
2351
2352 When you use the @code{tty} command or redirect input in the @code{run}
2353 command, only the input @emph{for your program} is affected.  The input
2354 for @value{GDBN} still comes from your terminal.  @code{tty} is an alias
2355 for @code{set inferior-tty}.
2356
2357 @cindex inferior tty
2358 @cindex set inferior controlling terminal
2359 You can use the @code{show inferior-tty} command to tell @value{GDBN} to
2360 display the name of the terminal that will be used for future runs of your
2361 program.
2362
2363 @table @code
2364 @item set inferior-tty /dev/ttyb
2365 @kindex set inferior-tty
2366 Set the tty for the program being debugged to /dev/ttyb.
2367
2368 @item show inferior-tty
2369 @kindex show inferior-tty
2370 Show the current tty for the program being debugged.
2371 @end table
2372
2373 @node Attach
2374 @section Debugging an Already-running Process
2375 @kindex attach
2376 @cindex attach
2377
2378 @table @code
2379 @item attach @var{process-id}
2380 This command attaches to a running process---one that was started
2381 outside @value{GDBN}.  (@code{info files} shows your active
2382 targets.)  The command takes as argument a process ID.  The usual way to
2383 find out the @var{process-id} of a Unix process is with the @code{ps} utility,
2384 or with the @samp{jobs -l} shell command.
2385
2386 @code{attach} does not repeat if you press @key{RET} a second time after
2387 executing the command.
2388 @end table
2389
2390 To use @code{attach}, your program must be running in an environment
2391 which supports processes; for example, @code{attach} does not work for
2392 programs on bare-board targets that lack an operating system.  You must
2393 also have permission to send the process a signal.
2394
2395 When you use @code{attach}, the debugger finds the program running in
2396 the process first by looking in the current working directory, then (if
2397 the program is not found) by using the source file search path
2398 (@pxref{Source Path, ,Specifying Source Directories}).  You can also use
2399 the @code{file} command to load the program.  @xref{Files, ,Commands to
2400 Specify Files}.
2401
2402 The first thing @value{GDBN} does after arranging to debug the specified
2403 process is to stop it.  You can examine and modify an attached process
2404 with all the @value{GDBN} commands that are ordinarily available when
2405 you start processes with @code{run}.  You can insert breakpoints; you
2406 can step and continue; you can modify storage.  If you would rather the
2407 process continue running, you may use the @code{continue} command after
2408 attaching @value{GDBN} to the process.
2409
2410 @table @code
2411 @kindex detach
2412 @item detach
2413 When you have finished debugging the attached process, you can use the
2414 @code{detach} command to release it from @value{GDBN} control.  Detaching
2415 the process continues its execution.  After the @code{detach} command,
2416 that process and @value{GDBN} become completely independent once more, and you
2417 are ready to @code{attach} another process or start one with @code{run}.
2418 @code{detach} does not repeat if you press @key{RET} again after
2419 executing the command.
2420 @end table
2421
2422 If you exit @value{GDBN} while you have an attached process, you detach
2423 that process.  If you use the @code{run} command, you kill that process.
2424 By default, @value{GDBN} asks for confirmation if you try to do either of these
2425 things; you can control whether or not you need to confirm by using the
2426 @code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
2427 Messages}).
2428
2429 @node Kill Process
2430 @section Killing the Child Process
2431
2432 @table @code
2433 @kindex kill
2434 @item kill
2435 Kill the child process in which your program is running under @value{GDBN}.
2436 @end table
2437
2438 This command is useful if you wish to debug a core dump instead of a
2439 running process.  @value{GDBN} ignores any core dump file while your program
2440 is running.
2441
2442 On some operating systems, a program cannot be executed outside @value{GDBN}
2443 while you have breakpoints set on it inside @value{GDBN}.  You can use the
2444 @code{kill} command in this situation to permit running your program
2445 outside the debugger.
2446
2447 The @code{kill} command is also useful if you wish to recompile and
2448 relink your program, since on many systems it is impossible to modify an
2449 executable file while it is running in a process.  In this case, when you
2450 next type @code{run}, @value{GDBN} notices that the file has changed, and
2451 reads the symbol table again (while trying to preserve your current
2452 breakpoint settings).
2453
2454 @node Inferiors and Programs
2455 @section Debugging Multiple Inferiors and Programs
2456
2457 @value{GDBN} lets you run and debug multiple programs in a single
2458 session.  In addition, @value{GDBN} on some systems may let you run
2459 several programs simultaneously (otherwise you have to exit from one
2460 before starting another).  In the most general case, you can have
2461 multiple threads of execution in each of multiple processes, launched
2462 from multiple executables.
2463
2464 @cindex inferior
2465 @value{GDBN} represents the state of each program execution with an
2466 object called an @dfn{inferior}.  An inferior typically corresponds to
2467 a process, but is more general and applies also to targets that do not
2468 have processes.  Inferiors may be created before a process runs, and
2469 may be retained after a process exits.  Inferiors have unique
2470 identifiers that are different from process ids.  Usually each
2471 inferior will also have its own distinct address space, although some
2472 embedded targets may have several inferiors running in different parts
2473 of a single address space.  Each inferior may in turn have multiple
2474 threads running in it.
2475
2476 To find out what inferiors exist at any moment, use @w{@code{info
2477 inferiors}}:
2478
2479 @table @code
2480 @kindex info inferiors
2481 @item info inferiors
2482 Print a list of all inferiors currently being managed by @value{GDBN}.
2483
2484 @value{GDBN} displays for each inferior (in this order):
2485
2486 @enumerate
2487 @item
2488 the inferior number assigned by @value{GDBN}
2489
2490 @item
2491 the target system's inferior identifier
2492
2493 @item
2494 the name of the executable the inferior is running.
2495
2496 @end enumerate
2497
2498 @noindent
2499 An asterisk @samp{*} preceding the @value{GDBN} inferior number
2500 indicates the current inferior.
2501
2502 For example,
2503 @end table
2504 @c end table here to get a little more width for example
2505
2506 @smallexample
2507 (@value{GDBP}) info inferiors
2508   Num  Description       Executable
2509   2    process 2307      hello
2510 * 1    process 3401      goodbye
2511 @end smallexample
2512
2513 To switch focus between inferiors, use the @code{inferior} command:
2514
2515 @table @code
2516 @kindex inferior @var{infno}
2517 @item inferior @var{infno}
2518 Make inferior number @var{infno} the current inferior.  The argument
2519 @var{infno} is the inferior number assigned by @value{GDBN}, as shown
2520 in the first field of the @samp{info inferiors} display.
2521 @end table
2522
2523
2524 You can get multiple executables into a debugging session via the
2525 @code{add-inferior} and @w{@code{clone-inferior}} commands.  On some
2526 systems @value{GDBN} can add inferiors to the debug session
2527 automatically by following calls to @code{fork} and @code{exec}.  To
2528 remove inferiors from the debugging session use the
2529 @w{@code{remove-inferiors}} command.
2530
2531 @table @code
2532 @kindex add-inferior
2533 @item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
2534 Adds @var{n} inferiors to be run using @var{executable} as the
2535 executable.  @var{n} defaults to 1.  If no executable is specified,
2536 the inferiors begins empty, with no program.  You can still assign or
2537 change the program assigned to the inferior at any time by using the
2538 @code{file} command with the executable name as its argument.
2539
2540 @kindex clone-inferior
2541 @item clone-inferior [ -copies @var{n} ] [ @var{infno} ]
2542 Adds @var{n} inferiors ready to execute the same program as inferior
2543 @var{infno}.  @var{n} defaults to 1.  @var{infno} defaults to the
2544 number of the current inferior.  This is a convenient command when you
2545 want to run another instance of the inferior you are debugging.
2546
2547 @smallexample
2548 (@value{GDBP}) info inferiors
2549   Num  Description       Executable
2550 * 1    process 29964     helloworld
2551 (@value{GDBP}) clone-inferior
2552 Added inferior 2.
2553 1 inferiors added.
2554 (@value{GDBP}) info inferiors
2555   Num  Description       Executable
2556   2    <null>            helloworld
2557 * 1    process 29964     helloworld
2558 @end smallexample
2559
2560 You can now simply switch focus to inferior 2 and run it.
2561
2562 @kindex remove-inferiors
2563 @item remove-inferiors @var{infno}@dots{}
2564 Removes the inferior or inferiors @var{infno}@dots{}.  It is not
2565 possible to remove an inferior that is running with this command.  For
2566 those, use the @code{kill} or @code{detach} command first.
2567
2568 @end table
2569
2570 To quit debugging one of the running inferiors that is not the current
2571 inferior, you can either detach from it by using the @w{@code{detach
2572 inferior}} command (allowing it to run independently), or kill it
2573 using the @w{@code{kill inferiors}} command:
2574
2575 @table @code
2576 @kindex detach inferiors @var{infno}@dots{}
2577 @item detach inferior @var{infno}@dots{}
2578 Detach from the inferior or inferiors identified by @value{GDBN}
2579 inferior number(s) @var{infno}@dots{}.  Note that the inferior's entry
2580 still stays on the list of inferiors shown by @code{info inferiors},
2581 but its Description will show @samp{<null>}.
2582
2583 @kindex kill inferiors @var{infno}@dots{}
2584 @item kill inferiors @var{infno}@dots{}
2585 Kill the inferior or inferiors identified by @value{GDBN} inferior
2586 number(s) @var{infno}@dots{}.  Note that the inferior's entry still
2587 stays on the list of inferiors shown by @code{info inferiors}, but its
2588 Description will show @samp{<null>}.
2589 @end table
2590
2591 After the successful completion of a command such as @code{detach},
2592 @code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after
2593 a normal process exit, the inferior is still valid and listed with
2594 @code{info inferiors}, ready to be restarted.
2595
2596
2597 To be notified when inferiors are started or exit under @value{GDBN}'s
2598 control use @w{@code{set print inferior-events}}:
2599
2600 @table @code
2601 @kindex set print inferior-events
2602 @cindex print messages on inferior start and exit
2603 @item set print inferior-events
2604 @itemx set print inferior-events on
2605 @itemx set print inferior-events off
2606 The @code{set print inferior-events} command allows you to enable or
2607 disable printing of messages when @value{GDBN} notices that new
2608 inferiors have started or that inferiors have exited or have been
2609 detached.  By default, these messages will not be printed.
2610
2611 @kindex show print inferior-events
2612 @item show print inferior-events
2613 Show whether messages will be printed when @value{GDBN} detects that
2614 inferiors have started, exited or have been detached.
2615 @end table
2616
2617 Many commands will work the same with multiple programs as with a
2618 single program: e.g., @code{print myglobal} will simply display the
2619 value of @code{myglobal} in the current inferior.
2620
2621
2622 Occasionaly, when debugging @value{GDBN} itself, it may be useful to
2623 get more info about the relationship of inferiors, programs, address
2624 spaces in a debug session.  You can do that with the @w{@code{maint
2625 info program-spaces}} command.
2626
2627 @table @code
2628 @kindex maint info program-spaces
2629 @item maint info program-spaces
2630 Print a list of all program spaces currently being managed by
2631 @value{GDBN}.
2632
2633 @value{GDBN} displays for each program space (in this order):
2634
2635 @enumerate
2636 @item
2637 the program space number assigned by @value{GDBN}
2638
2639 @item
2640 the name of the executable loaded into the program space, with e.g.,
2641 the @code{file} command.
2642
2643 @end enumerate
2644
2645 @noindent
2646 An asterisk @samp{*} preceding the @value{GDBN} program space number
2647 indicates the current program space.
2648
2649 In addition, below each program space line, @value{GDBN} prints extra
2650 information that isn't suitable to display in tabular form.  For
2651 example, the list of inferiors bound to the program space.
2652
2653 @smallexample
2654 (@value{GDBP}) maint info program-spaces
2655   Id   Executable
2656   2    goodbye
2657         Bound inferiors: ID 1 (process 21561)
2658 * 1    hello
2659 @end smallexample
2660
2661 Here we can see that no inferior is running the program @code{hello},
2662 while @code{process 21561} is running the program @code{goodbye}.  On
2663 some targets, it is possible that multiple inferiors are bound to the
2664 same program space.  The most common example is that of debugging both
2665 the parent and child processes of a @code{vfork} call.  For example,
2666
2667 @smallexample
2668 (@value{GDBP}) maint info program-spaces
2669   Id   Executable
2670 * 1    vfork-test
2671         Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
2672 @end smallexample
2673
2674 Here, both inferior 2 and inferior 1 are running in the same program
2675 space as a result of inferior 1 having executed a @code{vfork} call.
2676 @end table
2677
2678 @node Threads
2679 @section Debugging Programs with Multiple Threads
2680
2681 @cindex threads of execution
2682 @cindex multiple threads
2683 @cindex switching threads
2684 In some operating systems, such as HP-UX and Solaris, a single program
2685 may have more than one @dfn{thread} of execution.  The precise semantics
2686 of threads differ from one operating system to another, but in general
2687 the threads of a single program are akin to multiple processes---except
2688 that they share one address space (that is, they can all examine and
2689 modify the same variables).  On the other hand, each thread has its own
2690 registers and execution stack, and perhaps private memory.
2691
2692 @value{GDBN} provides these facilities for debugging multi-thread
2693 programs:
2694
2695 @itemize @bullet
2696 @item automatic notification of new threads
2697 @item @samp{thread @var{threadno}}, a command to switch among threads
2698 @item @samp{info threads}, a command to inquire about existing threads
2699 @item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}},
2700 a command to apply a command to a list of threads
2701 @item thread-specific breakpoints
2702 @item @samp{set print thread-events}, which controls printing of 
2703 messages on thread start and exit.
2704 @item @samp{set libthread-db-search-path @var{path}}, which lets
2705 the user specify which @code{libthread_db} to use if the default choice
2706 isn't compatible with the program.
2707 @end itemize
2708
2709 @quotation
2710 @emph{Warning:} These facilities are not yet available on every
2711 @value{GDBN} configuration where the operating system supports threads.
2712 If your @value{GDBN} does not support threads, these commands have no
2713 effect.  For example, a system without thread support shows no output
2714 from @samp{info threads}, and always rejects the @code{thread} command,
2715 like this:
2716
2717 @smallexample
2718 (@value{GDBP}) info threads
2719 (@value{GDBP}) thread 1
2720 Thread ID 1 not known.  Use the "info threads" command to
2721 see the IDs of currently known threads.
2722 @end smallexample
2723 @c FIXME to implementors: how hard would it be to say "sorry, this GDB
2724 @c                        doesn't support threads"?
2725 @end quotation
2726
2727 @cindex focus of debugging
2728 @cindex current thread
2729 The @value{GDBN} thread debugging facility allows you to observe all
2730 threads while your program runs---but whenever @value{GDBN} takes
2731 control, one thread in particular is always the focus of debugging.
2732 This thread is called the @dfn{current thread}.  Debugging commands show
2733 program information from the perspective of the current thread.
2734
2735 @cindex @code{New} @var{systag} message
2736 @cindex thread identifier (system)
2737 @c FIXME-implementors!! It would be more helpful if the [New...] message
2738 @c included GDB's numeric thread handle, so you could just go to that
2739 @c thread without first checking `info threads'.
2740 Whenever @value{GDBN} detects a new thread in your program, it displays
2741 the target system's identification for the thread with a message in the
2742 form @samp{[New @var{systag}]}.  @var{systag} is a thread identifier
2743 whose form varies depending on the particular system.  For example, on
2744 @sc{gnu}/Linux, you might see
2745
2746 @smallexample
2747 [New Thread 0x41e02940 (LWP 25582)]
2748 @end smallexample
2749
2750 @noindent
2751 when @value{GDBN} notices a new thread.  In contrast, on an SGI system,
2752 the @var{systag} is simply something like @samp{process 368}, with no
2753 further qualifier.
2754
2755 @c FIXME!! (1) Does the [New...] message appear even for the very first
2756 @c         thread of a program, or does it only appear for the
2757 @c         second---i.e.@: when it becomes obvious we have a multithread
2758 @c         program?
2759 @c         (2) *Is* there necessarily a first thread always?  Or do some
2760 @c         multithread systems permit starting a program with multiple
2761 @c         threads ab initio?
2762
2763 @cindex thread number
2764 @cindex thread identifier (GDB)
2765 For debugging purposes, @value{GDBN} associates its own thread
2766 number---always a single integer---with each thread in your program.
2767
2768 @table @code
2769 @kindex info threads
2770 @item info threads @r{[}@var{id}@dots{}@r{]}
2771 Display a summary of all threads currently in your program.  Optional 
2772 argument @var{id}@dots{} is one or more thread ids separated by spaces, and
2773 means to print information only about the specified thread or threads.
2774 @value{GDBN} displays for each thread (in this order):
2775
2776 @enumerate
2777 @item
2778 the thread number assigned by @value{GDBN}
2779
2780 @item
2781 the target system's thread identifier (@var{systag})
2782
2783 @item
2784 the thread's name, if one is known.  A thread can either be named by
2785 the user (see @code{thread name}, below), or, in some cases, by the
2786 program itself.
2787
2788 @item
2789 the current stack frame summary for that thread
2790 @end enumerate
2791
2792 @noindent
2793 An asterisk @samp{*} to the left of the @value{GDBN} thread number
2794 indicates the current thread.
2795
2796 For example,
2797 @end table
2798 @c end table here to get a little more width for example
2799
2800 @smallexample
2801 (@value{GDBP}) info threads
2802   Id   Target Id         Frame
2803   3    process 35 thread 27  0x34e5 in sigpause ()
2804   2    process 35 thread 23  0x34e5 in sigpause ()
2805 * 1    process 35 thread 13  main (argc=1, argv=0x7ffffff8)
2806     at threadtest.c:68
2807 @end smallexample
2808
2809 On Solaris, you can display more information about user threads with a
2810 Solaris-specific command:
2811
2812 @table @code
2813 @item maint info sol-threads
2814 @kindex maint info sol-threads
2815 @cindex thread info (Solaris)
2816 Display info on Solaris user threads.
2817 @end table
2818
2819 @table @code
2820 @kindex thread @var{threadno}
2821 @item thread @var{threadno}
2822 Make thread number @var{threadno} the current thread.  The command
2823 argument @var{threadno} is the internal @value{GDBN} thread number, as
2824 shown in the first field of the @samp{info threads} display.
2825 @value{GDBN} responds by displaying the system identifier of the thread
2826 you selected, and its current stack frame summary:
2827
2828 @smallexample
2829 (@value{GDBP}) thread 2
2830 [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
2831 #0  some_function (ignore=0x0) at example.c:8
2832 8           printf ("hello\n");
2833 @end smallexample
2834
2835 @noindent
2836 As with the @samp{[New @dots{}]} message, the form of the text after
2837 @samp{Switching to} depends on your system's conventions for identifying
2838 threads.
2839
2840 @vindex $_thread@r{, convenience variable}
2841 The debugger convenience variable @samp{$_thread} contains the number
2842 of the current thread.  You may find this useful in writing breakpoint
2843 conditional expressions, command scripts, and so forth.  See
2844 @xref{Convenience Vars,, Convenience Variables}, for general
2845 information on convenience variables.
2846
2847 @kindex thread apply
2848 @cindex apply command to several threads
2849 @item thread apply [@var{threadno} | all] @var{command}
2850 The @code{thread apply} command allows you to apply the named
2851 @var{command} to one or more threads.  Specify the numbers of the
2852 threads that you want affected with the command argument
2853 @var{threadno}.  It can be a single thread number, one of the numbers
2854 shown in the first field of the @samp{info threads} display; or it
2855 could be a range of thread numbers, as in @code{2-4}.  To apply a
2856 command to all threads, type @kbd{thread apply all @var{command}}.
2857
2858 @kindex thread name
2859 @cindex name a thread
2860 @item thread name [@var{name}]
2861 This command assigns a name to the current thread.  If no argument is
2862 given, any existing user-specified name is removed.  The thread name
2863 appears in the @samp{info threads} display.
2864
2865 On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to
2866 determine the name of the thread as given by the OS.  On these
2867 systems, a name specified with @samp{thread name} will override the
2868 system-give name, and removing the user-specified name will cause
2869 @value{GDBN} to once again display the system-specified name.
2870
2871 @kindex thread find
2872 @cindex search for a thread
2873 @item thread find [@var{regexp}]
2874 Search for and display thread ids whose name or @var{systag}
2875 matches the supplied regular expression.
2876
2877 As well as being the complement to the @samp{thread name} command, 
2878 this command also allows you to identify a thread by its target 
2879 @var{systag}.  For instance, on @sc{gnu}/Linux, the target @var{systag}
2880 is the LWP id.
2881
2882 @smallexample
2883 (@value{GDBN}) thread find 26688
2884 Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
2885 (@value{GDBN}) info thread 4
2886   Id   Target Id         Frame 
2887   4    Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
2888 @end smallexample
2889
2890 @kindex set print thread-events
2891 @cindex print messages on thread start and exit
2892 @item set print thread-events
2893 @itemx set print thread-events on
2894 @itemx set print thread-events off
2895 The @code{set print thread-events} command allows you to enable or
2896 disable printing of messages when @value{GDBN} notices that new threads have
2897 started or that threads have exited.  By default, these messages will
2898 be printed if detection of these events is supported by the target.
2899 Note that these messages cannot be disabled on all targets.
2900
2901 @kindex show print thread-events
2902 @item show print thread-events
2903 Show whether messages will be printed when @value{GDBN} detects that threads
2904 have started and exited.
2905 @end table
2906
2907 @xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
2908 more information about how @value{GDBN} behaves when you stop and start
2909 programs with multiple threads.
2910
2911 @xref{Set Watchpoints,,Setting Watchpoints}, for information about
2912 watchpoints in programs with multiple threads.
2913
2914 @anchor{set libthread-db-search-path}
2915 @table @code
2916 @kindex set libthread-db-search-path
2917 @cindex search path for @code{libthread_db}
2918 @item set libthread-db-search-path @r{[}@var{path}@r{]}
2919 If this variable is set, @var{path} is a colon-separated list of
2920 directories @value{GDBN} will use to search for @code{libthread_db}.
2921 If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
2922 its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems).
2923 Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH}
2924 macro.
2925
2926 On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
2927 @code{libthread_db} library to obtain information about threads in the
2928 inferior process.  @value{GDBN} will use @samp{libthread-db-search-path}
2929 to find @code{libthread_db}.  @value{GDBN} also consults first if inferior
2930 specific thread debugging library loading is enabled
2931 by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}).
2932
2933 A special entry @samp{$sdir} for @samp{libthread-db-search-path}
2934 refers to the default system directories that are
2935 normally searched for loading shared libraries.  The @samp{$sdir} entry
2936 is the only kind not needing to be enabled by @samp{set auto-load libthread-db}
2937 (@pxref{libthread_db.so.1 file}).
2938
2939 A special entry @samp{$pdir} for @samp{libthread-db-search-path}
2940 refers to the directory from which @code{libpthread}
2941 was loaded in the inferior process.
2942
2943 For any @code{libthread_db} library @value{GDBN} finds in above directories,
2944 @value{GDBN} attempts to initialize it with the current inferior process.
2945 If this initialization fails (which could happen because of a version
2946 mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN}
2947 will unload @code{libthread_db}, and continue with the next directory.
2948 If none of @code{libthread_db} libraries initialize successfully,
2949 @value{GDBN} will issue a warning and thread debugging will be disabled.
2950
2951 Setting @code{libthread-db-search-path} is currently implemented
2952 only on some platforms.
2953
2954 @kindex show libthread-db-search-path 
2955 @item show libthread-db-search-path 
2956 Display current libthread_db search path.
2957
2958 @kindex set debug libthread-db
2959 @kindex show debug libthread-db
2960 @cindex debugging @code{libthread_db}
2961 @item set debug libthread-db
2962 @itemx show debug libthread-db
2963 Turns on or off display of @code{libthread_db}-related events.
2964 Use @code{1} to enable, @code{0} to disable.
2965 @end table
2966
2967 @node Forks
2968 @section Debugging Forks
2969
2970 @cindex fork, debugging programs which call
2971 @cindex multiple processes
2972 @cindex processes, multiple
2973 On most systems, @value{GDBN} has no special support for debugging
2974 programs which create additional processes using the @code{fork}
2975 function.  When a program forks, @value{GDBN} will continue to debug the
2976 parent process and the child process will run unimpeded.  If you have
2977 set a breakpoint in any code which the child then executes, the child
2978 will get a @code{SIGTRAP} signal which (unless it catches the signal)
2979 will cause it to terminate.
2980
2981 However, if you want to debug the child process there is a workaround
2982 which isn't too painful.  Put a call to @code{sleep} in the code which
2983 the child process executes after the fork.  It may be useful to sleep
2984 only if a certain environment variable is set, or a certain file exists,
2985 so that the delay need not occur when you don't want to run @value{GDBN}
2986 on the child.  While the child is sleeping, use the @code{ps} program to
2987 get its process ID.  Then tell @value{GDBN} (a new invocation of
2988 @value{GDBN} if you are also debugging the parent process) to attach to
2989 the child process (@pxref{Attach}).  From that point on you can debug
2990 the child process just like any other process which you attached to.
2991
2992 On some systems, @value{GDBN} provides support for debugging programs that
2993 create additional processes using the @code{fork} or @code{vfork} functions.
2994 Currently, the only platforms with this feature are HP-UX (11.x and later
2995 only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
2996
2997 By default, when a program forks, @value{GDBN} will continue to debug
2998 the parent process and the child process will run unimpeded.
2999
3000 If you want to follow the child process instead of the parent process,
3001 use the command @w{@code{set follow-fork-mode}}.
3002
3003 @table @code
3004 @kindex set follow-fork-mode
3005 @item set follow-fork-mode @var{mode}
3006 Set the debugger response to a program call of @code{fork} or
3007 @code{vfork}.  A call to @code{fork} or @code{vfork} creates a new
3008 process.  The @var{mode} argument can be:
3009
3010 @table @code
3011 @item parent
3012 The original process is debugged after a fork.  The child process runs
3013 unimpeded.  This is the default.
3014
3015 @item child
3016 The new process is debugged after a fork.  The parent process runs
3017 unimpeded.
3018
3019 @end table
3020
3021 @kindex show follow-fork-mode
3022 @item show follow-fork-mode
3023 Display the current debugger response to a @code{fork} or @code{vfork} call.
3024 @end table
3025
3026 @cindex debugging multiple processes
3027 On Linux, if you want to debug both the parent and child processes, use the
3028 command @w{@code{set detach-on-fork}}.
3029
3030 @table @code
3031 @kindex set detach-on-fork
3032 @item set detach-on-fork @var{mode}
3033 Tells gdb whether to detach one of the processes after a fork, or
3034 retain debugger control over them both.
3035
3036 @table @code
3037 @item on
3038 The child process (or parent process, depending on the value of
3039 @code{follow-fork-mode}) will be detached and allowed to run 
3040 independently.  This is the default.
3041
3042 @item off
3043 Both processes will be held under the control of @value{GDBN}.
3044 One process (child or parent, depending on the value of 
3045 @code{follow-fork-mode}) is debugged as usual, while the other
3046 is held suspended.  
3047
3048 @end table
3049
3050 @kindex show detach-on-fork
3051 @item show detach-on-fork
3052 Show whether detach-on-fork mode is on/off.
3053 @end table
3054
3055 If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
3056 will retain control of all forked processes (including nested forks).
3057 You can list the forked processes under the control of @value{GDBN} by
3058 using the @w{@code{info inferiors}} command, and switch from one fork
3059 to another by using the @code{inferior} command (@pxref{Inferiors and
3060 Programs, ,Debugging Multiple Inferiors and Programs}).
3061
3062 To quit debugging one of the forked processes, you can either detach
3063 from it by using the @w{@code{detach inferiors}} command (allowing it
3064 to run independently), or kill it using the @w{@code{kill inferiors}}
3065 command.  @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
3066 and Programs}.
3067
3068 If you ask to debug a child process and a @code{vfork} is followed by an
3069 @code{exec}, @value{GDBN} executes the new target up to the first
3070 breakpoint in the new target.  If you have a breakpoint set on
3071 @code{main} in your original program, the breakpoint will also be set on
3072 the child process's @code{main}.
3073
3074 On some systems, when a child process is spawned by @code{vfork}, you
3075 cannot debug the child or parent until an @code{exec} call completes.
3076
3077 If you issue a @code{run} command to @value{GDBN} after an @code{exec}
3078 call executes, the new target restarts.  To restart the parent
3079 process, use the @code{file} command with the parent executable name
3080 as its argument.  By default, after an @code{exec} call executes,
3081 @value{GDBN} discards the symbols of the previous executable image.
3082 You can change this behaviour with the @w{@code{set follow-exec-mode}}
3083 command.
3084
3085 @table @code
3086 @kindex set follow-exec-mode
3087 @item set follow-exec-mode @var{mode}
3088
3089 Set debugger response to a program call of @code{exec}.  An
3090 @code{exec} call replaces the program image of a process.
3091
3092 @code{follow-exec-mode} can be:
3093
3094 @table @code
3095 @item new
3096 @value{GDBN} creates a new inferior and rebinds the process to this
3097 new inferior.  The program the process was running before the
3098 @code{exec} call can be restarted afterwards by restarting the
3099 original inferior.
3100
3101 For example:
3102
3103 @smallexample
3104 (@value{GDBP}) info inferiors
3105 (gdb) info inferior
3106   Id   Description   Executable
3107 * 1    <null>        prog1
3108 (@value{GDBP}) run
3109 process 12020 is executing new program: prog2
3110 Program exited normally.
3111 (@value{GDBP}) info inferiors
3112   Id   Description   Executable
3113 * 2    <null>        prog2
3114   1    <null>        prog1
3115 @end smallexample
3116
3117 @item same
3118 @value{GDBN} keeps the process bound to the same inferior.  The new
3119 executable image replaces the previous executable loaded in the
3120 inferior.  Restarting the inferior after the @code{exec} call, with
3121 e.g., the @code{run} command, restarts the executable the process was
3122 running after the @code{exec} call.  This is the default mode.
3123
3124 For example:
3125
3126 @smallexample
3127 (@value{GDBP}) info inferiors
3128   Id   Description   Executable
3129 * 1    <null>        prog1
3130 (@value{GDBP}) run
3131 process 12020 is executing new program: prog2
3132 Program exited normally.
3133 (@value{GDBP}) info inferiors
3134   Id   Description   Executable
3135 * 1    <null>        prog2
3136 @end smallexample
3137
3138 @end table
3139 @end table
3140
3141 You can use the @code{catch} command to make @value{GDBN} stop whenever
3142 a @code{fork}, @code{vfork}, or @code{exec} call is made.  @xref{Set
3143 Catchpoints, ,Setting Catchpoints}.
3144
3145 @node Checkpoint/Restart
3146 @section Setting a @emph{Bookmark} to Return to Later
3147
3148 @cindex checkpoint
3149 @cindex restart
3150 @cindex bookmark
3151 @cindex snapshot of a process
3152 @cindex rewind program state
3153
3154 On certain operating systems@footnote{Currently, only
3155 @sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
3156 program's state, called a @dfn{checkpoint}, and come back to it
3157 later.
3158
3159 Returning to a checkpoint effectively undoes everything that has
3160 happened in the program since the @code{checkpoint} was saved.  This
3161 includes changes in memory, registers, and even (within some limits)
3162 system state.  Effectively, it is like going back in time to the
3163 moment when the checkpoint was saved.
3164
3165 Thus, if you're stepping thru a program and you think you're 
3166 getting close to the point where things go wrong, you can save
3167 a checkpoint.  Then, if you accidentally go too far and miss
3168 the critical statement, instead of having to restart your program
3169 from the beginning, you can just go back to the checkpoint and
3170 start again from there.
3171
3172 This can be especially useful if it takes a lot of time or 
3173 steps to reach the point where you think the bug occurs.  
3174
3175 To use the @code{checkpoint}/@code{restart} method of debugging:
3176
3177 @table @code
3178 @kindex checkpoint
3179 @item checkpoint
3180 Save a snapshot of the debugged program's current execution state.
3181 The @code{checkpoint} command takes no arguments, but each checkpoint
3182 is assigned a small integer id, similar to a breakpoint id.
3183
3184 @kindex info checkpoints
3185 @item info checkpoints
3186 List the checkpoints that have been saved in the current debugging
3187 session.  For each checkpoint, the following information will be
3188 listed:
3189
3190 @table @code
3191 @item Checkpoint ID
3192 @item Process ID
3193 @item Code Address
3194 @item Source line, or label
3195 @end table
3196
3197 @kindex restart @var{checkpoint-id}
3198 @item restart @var{checkpoint-id}
3199 Restore the program state that was saved as checkpoint number
3200 @var{checkpoint-id}.  All program variables, registers, stack frames
3201 etc.@:  will be returned to the values that they had when the checkpoint
3202 was saved.  In essence, gdb will ``wind back the clock'' to the point
3203 in time when the checkpoint was saved.
3204
3205 Note that breakpoints, @value{GDBN} variables, command history etc.
3206 are not affected by restoring a checkpoint.  In general, a checkpoint
3207 only restores things that reside in the program being debugged, not in
3208 the debugger.
3209
3210 @kindex delete checkpoint @var{checkpoint-id}
3211 @item delete checkpoint @var{checkpoint-id}
3212 Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
3213
3214 @end table
3215
3216 Returning to a previously saved checkpoint will restore the user state
3217 of the program being debugged, plus a significant subset of the system
3218 (OS) state, including file pointers.  It won't ``un-write'' data from
3219 a file, but it will rewind the file pointer to the previous location,
3220 so that the previously written data can be overwritten.  For files
3221 opened in read mode, the pointer will also be restored so that the
3222 previously read data can be read again.
3223
3224 Of course, characters that have been sent to a printer (or other
3225 external device) cannot be ``snatched back'', and characters received
3226 from eg.@: a serial device can be removed from internal program buffers,
3227 but they cannot be ``pushed back'' into the serial pipeline, ready to
3228 be received again.  Similarly, the actual contents of files that have
3229 been changed cannot be restored (at this time).
3230
3231 However, within those constraints, you actually can ``rewind'' your
3232 program to a previously saved point in time, and begin debugging it
3233 again --- and you can change the course of events so as to debug a
3234 different execution path this time.
3235
3236 @cindex checkpoints and process id
3237 Finally, there is one bit of internal program state that will be
3238 different when you return to a checkpoint --- the program's process
3239 id.  Each checkpoint will have a unique process id (or @var{pid}), 
3240 and each will be different from the program's original @var{pid}.
3241 If your program has saved a local copy of its process id, this could
3242 potentially pose a problem.
3243
3244 @subsection A Non-obvious Benefit of Using Checkpoints
3245
3246 On some systems such as @sc{gnu}/Linux, address space randomization
3247 is performed on new processes for security reasons.  This makes it 
3248 difficult or impossible to set a breakpoint, or watchpoint, on an
3249 absolute address if you have to restart the program, since the 
3250 absolute location of a symbol will change from one execution to the
3251 next.
3252
3253 A checkpoint, however, is an @emph{identical} copy of a process. 
3254 Therefore if you create a checkpoint at (eg.@:) the start of main, 
3255 and simply return to that checkpoint instead of restarting the 
3256 process, you can avoid the effects of address randomization and
3257 your symbols will all stay in the same place.
3258
3259 @node Stopping
3260 @chapter Stopping and Continuing
3261
3262 The principal purposes of using a debugger are so that you can stop your
3263 program before it terminates; or so that, if your program runs into
3264 trouble, you can investigate and find out why.
3265
3266 Inside @value{GDBN}, your program may stop for any of several reasons,
3267 such as a signal, a breakpoint, or reaching a new line after a
3268 @value{GDBN} command such as @code{step}.  You may then examine and
3269 change variables, set new breakpoints or remove old ones, and then
3270 continue execution.  Usually, the messages shown by @value{GDBN} provide
3271 ample explanation of the status of your program---but you can also
3272 explicitly request this information at any time.
3273
3274 @table @code
3275 @kindex info program
3276 @item info program
3277 Display information about the status of your program: whether it is
3278 running or not, what process it is, and why it stopped.
3279 @end table
3280
3281 @menu
3282 * Breakpoints::                 Breakpoints, watchpoints, and catchpoints
3283 * Continuing and Stepping::     Resuming execution
3284 * Skipping Over Functions and Files::
3285                                 Skipping over functions and files
3286 * Signals::                     Signals
3287 * Thread Stops::                Stopping and starting multi-thread programs
3288 @end menu
3289
3290 @node Breakpoints
3291 @section Breakpoints, Watchpoints, and Catchpoints
3292
3293 @cindex breakpoints
3294 A @dfn{breakpoint} makes your program stop whenever a certain point in
3295 the program is reached.  For each breakpoint, you can add conditions to
3296 control in finer detail whether your program stops.  You can set
3297 breakpoints with the @code{break} command and its variants (@pxref{Set
3298 Breaks, ,Setting Breakpoints}), to specify the place where your program
3299 should stop by line number, function name or exact address in the
3300 program.
3301
3302 On some systems, you can set breakpoints in shared libraries before
3303 the executable is run.  There is a minor limitation on HP-UX systems:
3304 you must wait until the executable is run in order to set breakpoints
3305 in shared library routines that are not called directly by the program
3306 (for example, routines that are arguments in a @code{pthread_create}
3307 call).
3308
3309 @cindex watchpoints
3310 @cindex data breakpoints
3311 @cindex memory tracing
3312 @cindex breakpoint on memory address
3313 @cindex breakpoint on variable modification
3314 A @dfn{watchpoint} is a special breakpoint that stops your program
3315 when the value of an expression changes.  The expression may be a value
3316 of a variable, or it could involve values of one or more variables
3317 combined by operators, such as @samp{a + b}.  This is sometimes called
3318 @dfn{data breakpoints}.  You must use a different command to set
3319 watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside
3320 from that, you can manage a watchpoint like any other breakpoint: you
3321 enable, disable, and delete both breakpoints and watchpoints using the
3322 same commands.
3323
3324 You can arrange to have values from your program displayed automatically
3325 whenever @value{GDBN} stops at a breakpoint.  @xref{Auto Display,,
3326 Automatic Display}.
3327
3328 @cindex catchpoints
3329 @cindex breakpoint on events
3330 A @dfn{catchpoint} is another special breakpoint that stops your program
3331 when a certain kind of event occurs, such as the throwing of a C@t{++}
3332 exception or the loading of a library.  As with watchpoints, you use a
3333 different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
3334 Catchpoints}), but aside from that, you can manage a catchpoint like any
3335 other breakpoint.  (To stop when your program receives a signal, use the
3336 @code{handle} command; see @ref{Signals, ,Signals}.)
3337
3338 @cindex breakpoint numbers
3339 @cindex numbers for breakpoints
3340 @value{GDBN} assigns a number to each breakpoint, watchpoint, or
3341 catchpoint when you create it; these numbers are successive integers
3342 starting with one.  In many of the commands for controlling various
3343 features of breakpoints you use the breakpoint number to say which
3344 breakpoint you want to change.  Each breakpoint may be @dfn{enabled} or
3345 @dfn{disabled}; if disabled, it has no effect on your program until you
3346 enable it again.
3347
3348 @cindex breakpoint ranges
3349 @cindex ranges of breakpoints
3350 Some @value{GDBN} commands accept a range of breakpoints on which to
3351 operate.  A breakpoint range is either a single breakpoint number, like
3352 @samp{5}, or two such numbers, in increasing order, separated by a
3353 hyphen, like @samp{5-7}.  When a breakpoint range is given to a command,
3354 all breakpoints in that range are operated on.
3355
3356 @menu
3357 * Set Breaks::                  Setting breakpoints
3358 * Set Watchpoints::             Setting watchpoints
3359 * Set Catchpoints::             Setting catchpoints
3360 * Delete Breaks::               Deleting breakpoints
3361 * Disabling::                   Disabling breakpoints
3362 * Conditions::                  Break conditions
3363 * Break Commands::              Breakpoint command lists
3364 * Dynamic Printf::              Dynamic printf
3365 * Save Breakpoints::            How to save breakpoints in a file
3366 * Static Probe Points::         Listing static probe points
3367 * Error in Breakpoints::        ``Cannot insert breakpoints''
3368 * Breakpoint-related Warnings:: ``Breakpoint address adjusted...''
3369 @end menu
3370
3371 @node Set Breaks
3372 @subsection Setting Breakpoints
3373
3374 @c FIXME LMB what does GDB do if no code on line of breakpt?
3375 @c       consider in particular declaration with/without initialization.
3376 @c
3377 @c FIXME 2 is there stuff on this already? break at fun start, already init?
3378
3379 @kindex break
3380 @kindex b @r{(@code{break})}
3381 @vindex $bpnum@r{, convenience variable}
3382 @cindex latest breakpoint
3383 Breakpoints are set with the @code{break} command (abbreviated
3384 @code{b}).  The debugger convenience variable @samp{$bpnum} records the
3385 number of the breakpoint you've set most recently; see @ref{Convenience
3386 Vars,, Convenience Variables}, for a discussion of what you can do with
3387 convenience variables.
3388
3389 @table @code
3390 @item break @var{location}
3391 Set a breakpoint at the given @var{location}, which can specify a
3392 function name, a line number, or an address of an instruction.
3393 (@xref{Specify Location}, for a list of all the possible ways to
3394 specify a @var{location}.)  The breakpoint will stop your program just
3395 before it executes any of the code in the specified @var{location}.
3396
3397 When using source languages that permit overloading of symbols, such as
3398 C@t{++}, a function name may refer to more than one possible place to break.
3399 @xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
3400 that situation.
3401
3402 It is also possible to insert a breakpoint that will stop the program
3403 only if a specific thread (@pxref{Thread-Specific Breakpoints})
3404 or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
3405
3406 @item break
3407 When called without any arguments, @code{break} sets a breakpoint at
3408 the next instruction to be executed in the selected stack frame
3409 (@pxref{Stack, ,Examining the Stack}).  In any selected frame but the
3410 innermost, this makes your program stop as soon as control
3411 returns to that frame.  This is similar to the effect of a
3412 @code{finish} command in the frame inside the selected frame---except
3413 that @code{finish} does not leave an active breakpoint.  If you use
3414 @code{break} without an argument in the innermost frame, @value{GDBN} stops
3415 the next time it reaches the current location; this may be useful
3416 inside loops.
3417
3418 @value{GDBN} normally ignores breakpoints when it resumes execution, until at
3419 least one instruction has been executed.  If it did not do this, you
3420 would be unable to proceed past a breakpoint without first disabling the
3421 breakpoint.  This rule applies whether or not the breakpoint already
3422 existed when your program stopped.
3423
3424 @item break @dots{} if @var{cond}
3425 Set a breakpoint with condition @var{cond}; evaluate the expression
3426 @var{cond} each time the breakpoint is reached, and stop only if the
3427 value is nonzero---that is, if @var{cond} evaluates as true.
3428 @samp{@dots{}} stands for one of the possible arguments described
3429 above (or no argument) specifying where to break.  @xref{Conditions,
3430 ,Break Conditions}, for more information on breakpoint conditions.
3431
3432 @kindex tbreak
3433 @item tbreak @var{args}
3434 Set a breakpoint enabled only for one stop.  @var{args} are the
3435 same as for the @code{break} command, and the breakpoint is set in the same
3436 way, but the breakpoint is automatically deleted after the first time your
3437 program stops there.  @xref{Disabling, ,Disabling Breakpoints}.
3438
3439 @kindex hbreak
3440 @cindex hardware breakpoints
3441 @item hbreak @var{args}
3442 Set a hardware-assisted breakpoint.  @var{args} are the same as for the
3443 @code{break} command and the breakpoint is set in the same way, but the
3444 breakpoint requires hardware support and some target hardware may not
3445 have this support.  The main purpose of this is EPROM/ROM code
3446 debugging, so you can set a breakpoint at an instruction without
3447 changing the instruction.  This can be used with the new trap-generation
3448 provided by SPARClite DSU and most x86-based targets.  These targets
3449 will generate traps when a program accesses some data or instruction
3450 address that is assigned to the debug registers.  However the hardware
3451 breakpoint registers can take a limited number of breakpoints.  For
3452 example, on the DSU, only two data breakpoints can be set at a time, and
3453 @value{GDBN} will reject this command if more than two are used.  Delete
3454 or disable unused hardware breakpoints before setting new ones
3455 (@pxref{Disabling, ,Disabling Breakpoints}).
3456 @xref{Conditions, ,Break Conditions}.
3457 For remote targets, you can restrict the number of hardware
3458 breakpoints @value{GDBN} will use, see @ref{set remote
3459 hardware-breakpoint-limit}.
3460
3461 @kindex thbreak
3462 @item thbreak @var{args}
3463 Set a hardware-assisted breakpoint enabled only for one stop.  @var{args}
3464 are the same as for the @code{hbreak} command and the breakpoint is set in
3465 the same way.  However, like the @code{tbreak} command,
3466 the breakpoint is automatically deleted after the
3467 first time your program stops there.  Also, like the @code{hbreak}
3468 command, the breakpoint requires hardware support and some target hardware
3469 may not have this support.  @xref{Disabling, ,Disabling Breakpoints}.
3470 See also @ref{Conditions, ,Break Conditions}.
3471
3472 @kindex rbreak
3473 @cindex regular expression
3474 @cindex breakpoints at functions matching a regexp
3475 @cindex set breakpoints in many functions
3476 @item rbreak @var{regex}
3477 Set breakpoints on all functions matching the regular expression
3478 @var{regex}.  This command sets an unconditional breakpoint on all
3479 matches, printing a list of all breakpoints it set.  Once these
3480 breakpoints are set, they are treated just like the breakpoints set with
3481 the @code{break} command.  You can delete them, disable them, or make
3482 them conditional the same way as any other breakpoint.
3483
3484 The syntax of the regular expression is the standard one used with tools
3485 like @file{grep}.  Note that this is different from the syntax used by
3486 shells, so for instance @code{foo*} matches all functions that include
3487 an @code{fo} followed by zero or more @code{o}s.  There is an implicit
3488 @code{.*} leading and trailing the regular expression you supply, so to
3489 match only functions that begin with @code{foo}, use @code{^foo}.
3490
3491 @cindex non-member C@t{++} functions, set breakpoint in
3492 When debugging C@t{++} programs, @code{rbreak} is useful for setting
3493 breakpoints on overloaded functions that are not members of any special
3494 classes.
3495
3496 @cindex set breakpoints on all functions
3497 The @code{rbreak} command can be used to set breakpoints in
3498 @strong{all} the functions in a program, like this:
3499
3500 @smallexample
3501 (@value{GDBP}) rbreak .
3502 @end smallexample
3503
3504 @item rbreak @var{file}:@var{regex}
3505 If @code{rbreak} is called with a filename qualification, it limits
3506 the search for functions matching the given regular expression to the
3507 specified @var{file}.  This can be used, for example, to set breakpoints on
3508 every function in a given file:
3509
3510 @smallexample
3511 (@value{GDBP}) rbreak file.c:.
3512 @end smallexample
3513
3514 The colon separating the filename qualifier from the regex may
3515 optionally be surrounded by spaces.
3516
3517 @kindex info breakpoints
3518 @cindex @code{$_} and @code{info breakpoints}
3519 @item info breakpoints @r{[}@var{n}@dots{}@r{]}
3520 @itemx info break @r{[}@var{n}@dots{}@r{]}
3521 Print a table of all breakpoints, watchpoints, and catchpoints set and
3522 not deleted.  Optional argument @var{n} means print information only
3523 about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
3524 For each breakpoint, following columns are printed:
3525
3526 @table @emph
3527 @item Breakpoint Numbers
3528 @item Type
3529 Breakpoint, watchpoint, or catchpoint.
3530 @item Disposition
3531 Whether the breakpoint is marked to be disabled or deleted when hit.
3532 @item Enabled or Disabled
3533 Enabled breakpoints are marked with @samp{y}.  @samp{n} marks breakpoints
3534 that are not enabled.
3535 @item Address
3536 Where the breakpoint is in your program, as a memory address.  For a
3537 pending breakpoint whose address is not yet known, this field will
3538 contain @samp{<PENDING>}.  Such breakpoint won't fire until a shared
3539 library that has the symbol or line referred by breakpoint is loaded.
3540 See below for details.  A breakpoint with several locations will
3541 have @samp{<MULTIPLE>} in this field---see below for details.
3542 @item What
3543 Where the breakpoint is in the source for your program, as a file and
3544 line number.  For a pending breakpoint, the original string passed to
3545 the breakpoint command will be listed as it cannot be resolved until
3546 the appropriate shared library is loaded in the future.
3547 @end table
3548
3549 @noindent
3550 If a breakpoint is conditional, there are two evaluation modes: ``host'' and
3551 ``target''.  If mode is ``host'', breakpoint condition evaluation is done by
3552 @value{GDBN} on the host's side.  If it is ``target'', then the condition
3553 is evaluated by the target.  The @code{info break} command shows
3554 the condition on the line following the affected breakpoint, together with
3555 its condition evaluation mode in between parentheses.
3556
3557 Breakpoint commands, if any, are listed after that.  A pending breakpoint is
3558 allowed to have a condition specified for it.  The condition is not parsed for
3559 validity until a shared library is loaded that allows the pending
3560 breakpoint to resolve to a valid location.
3561
3562 @noindent
3563 @code{info break} with a breakpoint
3564 number @var{n} as argument lists only that breakpoint.  The
3565 convenience variable @code{$_} and the default examining-address for
3566 the @code{x} command are set to the address of the last breakpoint
3567 listed (@pxref{Memory, ,Examining Memory}).
3568
3569 @noindent
3570 @code{info break} displays a count of the number of times the breakpoint
3571 has been hit.  This is especially useful in conjunction with the
3572 @code{ignore} command.  You can ignore a large number of breakpoint
3573 hits, look at the breakpoint info to see how many times the breakpoint
3574 was hit, and then run again, ignoring one less than that number.  This
3575 will get you quickly to the last hit of that breakpoint.
3576
3577 @noindent
3578 For a breakpoints with an enable count (xref) greater than 1,
3579 @code{info break} also displays that count.
3580
3581 @end table
3582
3583 @value{GDBN} allows you to set any number of breakpoints at the same place in
3584 your program.  There is nothing silly or meaningless about this.  When
3585 the breakpoints are conditional, this is even useful
3586 (@pxref{Conditions, ,Break Conditions}).
3587
3588 @cindex multiple locations, breakpoints
3589 @cindex breakpoints, multiple locations
3590 It is possible that a breakpoint corresponds to several locations
3591 in your program.  Examples of this situation are:
3592
3593 @itemize @bullet
3594 @item
3595 Multiple functions in the program may have the same name.
3596
3597 @item
3598 For a C@t{++} constructor, the @value{NGCC} compiler generates several
3599 instances of the function body, used in different cases.
3600
3601 @item
3602 For a C@t{++} template function, a given line in the function can
3603 correspond to any number of instantiations.
3604
3605 @item
3606 For an inlined function, a given source line can correspond to
3607 several places where that function is inlined.
3608 @end itemize
3609
3610 In all those cases, @value{GDBN} will insert a breakpoint at all
3611 the relevant locations.
3612
3613 A breakpoint with multiple locations is displayed in the breakpoint
3614 table using several rows---one header row, followed by one row for
3615 each breakpoint location.  The header row has @samp{<MULTIPLE>} in the
3616 address column.  The rows for individual locations contain the actual
3617 addresses for locations, and show the functions to which those
3618 locations belong.  The number column for a location is of the form
3619 @var{breakpoint-number}.@var{location-number}.
3620
3621 For example:
3622
3623 @smallexample
3624 Num     Type           Disp Enb  Address    What
3625 1       breakpoint     keep y    <MULTIPLE>
3626         stop only if i==1
3627         breakpoint already hit 1 time
3628 1.1                         y    0x080486a2 in void foo<int>() at t.cc:8
3629 1.2                         y    0x080486ca in void foo<double>() at t.cc:8
3630 @end smallexample
3631
3632 Each location can be individually enabled or disabled by passing
3633 @var{breakpoint-number}.@var{location-number} as argument to the
3634 @code{enable} and @code{disable} commands.  Note that you cannot
3635 delete the individual locations from the list, you can only delete the
3636 entire list of locations that belong to their parent breakpoint (with
3637 the @kbd{delete @var{num}} command, where @var{num} is the number of
3638 the parent breakpoint, 1 in the above example).  Disabling or enabling
3639 the parent breakpoint (@pxref{Disabling}) affects all of the locations
3640 that belong to that breakpoint.
3641
3642 @cindex pending breakpoints
3643 It's quite common to have a breakpoint inside a shared library.
3644 Shared libraries can be loaded and unloaded explicitly,
3645 and possibly repeatedly, as the program is executed.  To support
3646 this use case, @value{GDBN} updates breakpoint locations whenever
3647 any shared library is loaded or unloaded.  Typically, you would
3648 set a breakpoint in a shared library at the beginning of your
3649 debugging session, when the library is not loaded, and when the
3650 symbols from the library are not available.  When you try to set
3651 breakpoint, @value{GDBN} will ask you if you want to set
3652 a so called @dfn{pending breakpoint}---breakpoint whose address
3653 is not yet resolved.
3654
3655 After the program is run, whenever a new shared library is loaded,
3656 @value{GDBN} reevaluates all the breakpoints.  When a newly loaded
3657 shared library contains the symbol or line referred to by some
3658 pending breakpoint, that breakpoint is resolved and becomes an
3659 ordinary breakpoint.  When a library is unloaded, all breakpoints
3660 that refer to its symbols or source lines become pending again.
3661
3662 This logic works for breakpoints with multiple locations, too.  For
3663 example, if you have a breakpoint in a C@t{++} template function, and
3664 a newly loaded shared library has an instantiation of that template,
3665 a new location is added to the list of locations for the breakpoint.
3666
3667 Except for having unresolved address, pending breakpoints do not
3668 differ from regular breakpoints.  You can set conditions or commands,
3669 enable and disable them and perform other breakpoint operations.
3670
3671 @value{GDBN} provides some additional commands for controlling what
3672 happens when the @samp{break} command cannot resolve breakpoint
3673 address specification to an address:
3674
3675 @kindex set breakpoint pending
3676 @kindex show breakpoint pending
3677 @table @code
3678 @item set breakpoint pending auto
3679 This is the default behavior.  When @value{GDBN} cannot find the breakpoint
3680 location, it queries you whether a pending breakpoint should be created.
3681
3682 @item set breakpoint pending on
3683 This indicates that an unrecognized breakpoint location should automatically
3684 result in a pending breakpoint being created.
3685
3686 @item set breakpoint pending off
3687 This indicates that pending breakpoints are not to be created.  Any
3688 unrecognized breakpoint location results in an error.  This setting does
3689 not affect any pending breakpoints previously created.
3690
3691 @item show breakpoint pending
3692 Show the current behavior setting for creating pending breakpoints.
3693 @end table
3694
3695 The settings above only affect the @code{break} command and its
3696 variants.  Once breakpoint is set, it will be automatically updated
3697 as shared libraries are loaded and unloaded.
3698
3699 @cindex automatic hardware breakpoints
3700 For some targets, @value{GDBN} can automatically decide if hardware or
3701 software breakpoints should be used, depending on whether the
3702 breakpoint address is read-only or read-write.  This applies to
3703 breakpoints set with the @code{break} command as well as to internal
3704 breakpoints set by commands like @code{next} and @code{finish}.  For
3705 breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
3706 breakpoints.
3707
3708 You can control this automatic behaviour with the following commands::
3709
3710 @kindex set breakpoint auto-hw
3711 @kindex show breakpoint auto-hw
3712 @table @code
3713 @item set breakpoint auto-hw on
3714 This is the default behavior.  When @value{GDBN} sets a breakpoint, it
3715 will try to use the target memory map to decide if software or hardware
3716 breakpoint must be used.
3717
3718 @item set breakpoint auto-hw off
3719 This indicates @value{GDBN} should not automatically select breakpoint
3720 type.  If the target provides a memory map, @value{GDBN} will warn when
3721 trying to set software breakpoint at a read-only address.
3722 @end table
3723
3724 @value{GDBN} normally implements breakpoints by replacing the program code
3725 at the breakpoint address with a special instruction, which, when
3726 executed, given control to the debugger.  By default, the program
3727 code is so modified only when the program is resumed.  As soon as
3728 the program stops, @value{GDBN} restores the original instructions.  This
3729 behaviour guards against leaving breakpoints inserted in the
3730 target should gdb abrubptly disconnect.  However, with slow remote
3731 targets, inserting and removing breakpoint can reduce the performance.
3732 This behavior can be controlled with the following commands::
3733
3734 @kindex set breakpoint always-inserted
3735 @kindex show breakpoint always-inserted
3736 @table @code
3737 @item set breakpoint always-inserted off
3738 All breakpoints, including newly added by the user, are inserted in
3739 the target only when the target is resumed.  All breakpoints are
3740 removed from the target when it stops.
3741
3742 @item set breakpoint always-inserted on
3743 Causes all breakpoints to be inserted in the target at all times.  If
3744 the user adds a new breakpoint, or changes an existing breakpoint, the
3745 breakpoints in the target are updated immediately.  A breakpoint is
3746 removed from the target only when breakpoint itself is removed.
3747
3748 @cindex non-stop mode, and @code{breakpoint always-inserted}
3749 @item set breakpoint always-inserted auto
3750 This is the default mode.  If @value{GDBN} is controlling the inferior
3751 in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
3752 @code{breakpoint always-inserted} mode is on.  If @value{GDBN} is
3753 controlling the inferior in all-stop mode, @value{GDBN} behaves as if
3754 @code{breakpoint always-inserted} mode is off.
3755 @end table
3756
3757 @value{GDBN} handles conditional breakpoints by evaluating these conditions
3758 when a breakpoint breaks.  If the condition is true, then the process being
3759 debugged stops, otherwise the process is resumed.
3760
3761 If the target supports evaluating conditions on its end, @value{GDBN} may
3762 download the breakpoint, together with its conditions, to it.
3763
3764 This feature can be controlled via the following commands:
3765
3766 @kindex set breakpoint condition-evaluation
3767 @kindex show breakpoint condition-evaluation
3768 @table @code
3769 @item set breakpoint condition-evaluation host
3770 This option commands @value{GDBN} to evaluate the breakpoint
3771 conditions on the host's side.  Unconditional breakpoints are sent to
3772 the target which in turn receives the triggers and reports them back to GDB
3773 for condition evaluation.  This is the standard evaluation mode.
3774
3775 @item set breakpoint condition-evaluation target
3776 This option commands @value{GDBN} to download breakpoint conditions
3777 to the target at the moment of their insertion.  The target
3778 is responsible for evaluating the conditional expression and reporting
3779 breakpoint stop events back to @value{GDBN} whenever the condition
3780 is true.  Due to limitations of target-side evaluation, some conditions
3781 cannot be evaluated there, e.g., conditions that depend on local data
3782 that is only known to the host.  Examples include
3783 conditional expressions involving convenience variables, complex types
3784 that cannot be handled by the agent expression parser and expressions
3785 that are too long to be sent over to the target, specially when the
3786 target is a remote system.  In these cases, the conditions will be
3787 evaluated by @value{GDBN}.
3788
3789 @item set breakpoint condition-evaluation auto
3790 This is the default mode.  If the target supports evaluating breakpoint
3791 conditions on its end, @value{GDBN} will download breakpoint conditions to
3792 the target (limitations mentioned previously apply).  If the target does
3793 not support breakpoint condition evaluation, then @value{GDBN} will fallback
3794 to evaluating all these conditions on the host's side.
3795 @end table
3796
3797
3798 @cindex negative breakpoint numbers
3799 @cindex internal @value{GDBN} breakpoints
3800 @value{GDBN} itself sometimes sets breakpoints in your program for
3801 special purposes, such as proper handling of @code{longjmp} (in C
3802 programs).  These internal breakpoints are assigned negative numbers,
3803 starting with @code{-1}; @samp{info breakpoints} does not display them.
3804 You can see these breakpoints with the @value{GDBN} maintenance command
3805 @samp{maint info breakpoints} (@pxref{maint info breakpoints}).
3806
3807
3808 @node Set Watchpoints
3809 @subsection Setting Watchpoints
3810
3811 @cindex setting watchpoints
3812 You can use a watchpoint to stop execution whenever the value of an
3813 expression changes, without having to predict a particular place where
3814 this may happen.  (This is sometimes called a @dfn{data breakpoint}.)
3815 The expression may be as simple as the value of a single variable, or
3816 as complex as many variables combined by operators.  Examples include:
3817
3818 @itemize @bullet
3819 @item
3820 A reference to the value of a single variable.
3821
3822 @item
3823 An address cast to an appropriate data type.  For example,
3824 @samp{*(int *)0x12345678} will watch a 4-byte region at the specified
3825 address (assuming an @code{int} occupies 4 bytes).
3826
3827 @item
3828 An arbitrarily complex expression, such as @samp{a*b + c/d}.  The
3829 expression can use any operators valid in the program's native
3830 language (@pxref{Languages}).
3831 @end itemize
3832
3833 You can set a watchpoint on an expression even if the expression can
3834 not be evaluated yet.  For instance, you can set a watchpoint on
3835 @samp{*global_ptr} before @samp{global_ptr} is initialized.
3836 @value{GDBN} will stop when your program sets @samp{global_ptr} and
3837 the expression produces a valid value.  If the expression becomes
3838 valid in some other way than changing a variable (e.g.@: if the memory
3839 pointed to by @samp{*global_ptr} becomes readable as the result of a
3840 @code{malloc} call), @value{GDBN} may not stop until the next time
3841 the expression changes.
3842
3843 @cindex software watchpoints
3844 @cindex hardware watchpoints
3845 Depending on your system, watchpoints may be implemented in software or
3846 hardware.  @value{GDBN} does software watchpointing by single-stepping your
3847 program and testing the variable's value each time, which is hundreds of
3848 times slower than normal execution.  (But this may still be worth it, to
3849 catch errors where you have no clue what part of your program is the
3850 culprit.)
3851
3852 On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
3853 x86-based targets, @value{GDBN} includes support for hardware
3854 watchpoints, which do not slow down the running of your program.
3855
3856 @table @code
3857 @kindex watch
3858 @item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
3859 Set a watchpoint for an expression.  @value{GDBN} will break when the
3860 expression @var{expr} is written into by the program and its value
3861 changes.  The simplest (and the most popular) use of this command is
3862 to watch the value of a single variable:
3863
3864 @smallexample
3865 (@value{GDBP}) watch foo
3866 @end smallexample
3867
3868 If the command includes a @code{@r{[}thread @var{threadnum}@r{]}}
3869 argument, @value{GDBN} breaks only when the thread identified by
3870 @var{threadnum} changes the value of @var{expr}.  If any other threads
3871 change the value of @var{expr}, @value{GDBN} will not break.  Note
3872 that watchpoints restricted to a single thread in this way only work
3873 with Hardware Watchpoints.
3874
3875 Ordinarily a watchpoint respects the scope of variables in @var{expr}
3876 (see below).  The @code{-location} argument tells @value{GDBN} to
3877 instead watch the memory referred to by @var{expr}.  In this case,
3878 @value{GDBN} will evaluate @var{expr}, take the address of the result,
3879 and watch the memory at that address.  The type of the result is used
3880 to determine the size of the watched memory.  If the expression's
3881 result does not have an address, then @value{GDBN} will print an
3882 error.
3883
3884 The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation
3885 of masked watchpoints, if the current architecture supports this
3886 feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC
3887 Embedded}.)  A @dfn{masked watchpoint} specifies a mask in addition
3888 to an address to watch.  The mask specifies that some bits of an address
3889 (the bits which are reset in the mask) should be ignored when matching
3890 the address accessed by the inferior against the watchpoint address.
3891 Thus, a masked watchpoint watches many addresses simultaneously---those
3892 addresses whose unmasked bits are identical to the unmasked bits in the
3893 watchpoint address.  The @code{mask} argument implies @code{-location}.
3894 Examples:
3895
3896 @smallexample
3897 (@value{GDBP}) watch foo mask 0xffff00ff
3898 (@value{GDBP}) watch *0xdeadbeef mask 0xffffff00
3899 @end smallexample
3900
3901 @kindex rwatch
3902 @item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
3903 Set a watchpoint that will break when the value of @var{expr} is read
3904 by the program.
3905
3906 @kindex awatch
3907 @item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{threadnum}@r{]} @r{[}mask @var{maskvalue}@r{]}
3908 Set a watchpoint that will break when @var{expr} is either read from
3909 or written into by the program.
3910
3911 @kindex info watchpoints @r{[}@var{n}@dots{}@r{]}
3912 @item info watchpoints @r{[}@var{n}@dots{}@r{]}
3913 This command prints a list of watchpoints, using the same format as
3914 @code{info break} (@pxref{Set Breaks}).
3915 @end table
3916
3917 If you watch for a change in a numerically entered address you need to
3918 dereference it, as the address itself is just a constant number which will
3919 never change.  @value{GDBN} refuses to create a watchpoint that watches
3920 a never-changing value:
3921
3922 @smallexample
3923 (@value{GDBP}) watch 0x600850
3924 Cannot watch constant value 0x600850.
3925 (@value{GDBP}) watch *(int *) 0x600850
3926 Watchpoint 1: *(int *) 6293584
3927 @end smallexample
3928
3929 @value{GDBN} sets a @dfn{hardware watchpoint} if possible.  Hardware
3930 watchpoints execute very quickly, and the debugger reports a change in
3931 value at the exact instruction where the change occurs.  If @value{GDBN}
3932 cannot set a hardware watchpoint, it sets a software watchpoint, which
3933 executes more slowly and reports the change in value at the next
3934 @emph{statement}, not the instruction, after the change occurs.
3935
3936 @cindex use only software watchpoints
3937 You can force @value{GDBN} to use only software watchpoints with the
3938 @kbd{set can-use-hw-watchpoints 0} command.  With this variable set to
3939 zero, @value{GDBN} will never try to use hardware watchpoints, even if
3940 the underlying system supports them.  (Note that hardware-assisted
3941 watchpoints that were set @emph{before} setting
3942 @code{can-use-hw-watchpoints} to zero will still use the hardware
3943 mechanism of watching expression values.)
3944
3945 @table @code
3946 @item set can-use-hw-watchpoints
3947 @kindex set can-use-hw-watchpoints
3948 Set whether or not to use hardware watchpoints.
3949
3950 @item show can-use-hw-watchpoints
3951 @kindex show can-use-hw-watchpoints
3952 Show the current mode of using hardware watchpoints.
3953 @end table
3954
3955 For remote targets, you can restrict the number of hardware
3956 watchpoints @value{GDBN} will use, see @ref{set remote
3957 hardware-breakpoint-limit}.
3958
3959 When you issue the @code{watch} command, @value{GDBN} reports
3960
3961 @smallexample
3962 Hardware watchpoint @var{num}: @var{expr}
3963 @end smallexample
3964
3965 @noindent
3966 if it was able to set a hardware watchpoint.
3967
3968 Currently, the @code{awatch} and @code{rwatch} commands can only set
3969 hardware watchpoints, because accesses to data that don't change the
3970 value of the watched expression cannot be detected without examining
3971 every instruction as it is being executed, and @value{GDBN} does not do
3972 that currently.  If @value{GDBN} finds that it is unable to set a
3973 hardware breakpoint with the @code{awatch} or @code{rwatch} command, it
3974 will print a message like this:
3975
3976 @smallexample
3977 Expression cannot be implemented with read/access watchpoint.
3978 @end smallexample
3979
3980 Sometimes, @value{GDBN} cannot set a hardware watchpoint because the
3981 data type of the watched expression is wider than what a hardware
3982 watchpoint on the target machine can handle.  For example, some systems
3983 can only watch regions that are up to 4 bytes wide; on such systems you
3984 cannot set hardware watchpoints for an expression that yields a
3985 double-precision floating-point number (which is typically 8 bytes
3986 wide).  As a work-around, it might be possible to break the large region
3987 into a series of smaller ones and watch them with separate watchpoints.
3988
3989 If you set too many hardware watchpoints, @value{GDBN} might be unable
3990 to insert all of them when you resume the execution of your program.
3991 Since the precise number of active watchpoints is unknown until such
3992 time as the program is about to be resumed, @value{GDBN} might not be
3993 able to warn you about this when you set the watchpoints, and the
3994 warning will be printed only when the program is resumed:
3995
3996 @smallexample
3997 Hardware watchpoint @var{num}: Could not insert watchpoint
3998 @end smallexample
3999
4000 @noindent
4001 If this happens, delete or disable some of the watchpoints.
4002
4003 Watching complex expressions that reference many variables can also
4004 exhaust the resources available for hardware-assisted watchpoints.
4005 That's because @value{GDBN} needs to watch every variable in the
4006 expression with separately allocated resources.
4007
4008 If you call a function interactively using @code{print} or @code{call},
4009 any watchpoints you have set will be inactive until @value{GDBN} reaches another
4010 kind of breakpoint or the call completes.
4011
4012 @value{GDBN} automatically deletes watchpoints that watch local
4013 (automatic) variables, or expressions that involve such variables, when
4014 they go out of scope, that is, when the execution leaves the block in
4015 which these variables were defined.  In particular, when the program
4016 being debugged terminates, @emph{all} local variables go out of scope,
4017 and so only watchpoints that watch global variables remain set.  If you
4018 rerun the program, you will need to set all such watchpoints again.  One
4019 way of doing that would be to set a code breakpoint at the entry to the
4020 @code{main} function and when it breaks, set all the watchpoints.
4021
4022 @cindex watchpoints and threads
4023 @cindex threads and watchpoints
4024 In multi-threaded programs, watchpoints will detect changes to the
4025 watched expression from every thread.
4026
4027 @quotation
4028 @emph{Warning:} In multi-threaded programs, software watchpoints
4029 have only limited usefulness.  If @value{GDBN} creates a software
4030 watchpoint, it can only watch the value of an expression @emph{in a
4031 single thread}.  If you are confident that the expression can only
4032 change due to the current thread's activity (and if you are also
4033 confident that no other thread can become current), then you can use
4034 software watchpoints as usual.  However, @value{GDBN} may not notice
4035 when a non-current thread's activity changes the expression.  (Hardware
4036 watchpoints, in contrast, watch an expression in all threads.)
4037 @end quotation
4038
4039 @xref{set remote hardware-watchpoint-limit}.
4040
4041 @node Set Catchpoints
4042 @subsection Setting Catchpoints
4043 @cindex catchpoints, setting
4044 @cindex exception handlers
4045 @cindex event handling
4046
4047 You can use @dfn{catchpoints} to cause the debugger to stop for certain
4048 kinds of program events, such as C@t{++} exceptions or the loading of a
4049 shared library.  Use the @code{catch} command to set a catchpoint.
4050
4051 @table @code
4052 @kindex catch
4053 @item catch @var{event}
4054 Stop when @var{event} occurs.  @var{event} can be any of the following:
4055 @table @code
4056 @item throw
4057 @cindex stop on C@t{++} exceptions
4058 The throwing of a C@t{++} exception.
4059
4060 @item catch
4061 The catching of a C@t{++} exception.
4062
4063 @item exception
4064 @cindex Ada exception catching
4065 @cindex catch Ada exceptions
4066 An Ada exception being raised.  If an exception name is specified
4067 at the end of the command (eg @code{catch exception Program_Error}),
4068 the debugger will stop only when this specific exception is raised.
4069 Otherwise, the debugger stops execution when any Ada exception is raised.
4070
4071 When inserting an exception catchpoint on a user-defined exception whose
4072 name is identical to one of the exceptions defined by the language, the
4073 fully qualified name must be used as the exception name.  Otherwise,
4074 @value{GDBN} will assume that it should stop on the pre-defined exception
4075 rather than the user-defined one.  For instance, assuming an exception
4076 called @code{Constraint_Error} is defined in package @code{Pck}, then
4077 the command to use to catch such exceptions is @kbd{catch exception
4078 Pck.Constraint_Error}.
4079
4080 @item exception unhandled
4081 An exception that was raised but is not handled by the program.
4082
4083 @item assert
4084 A failed Ada assertion.
4085
4086 @item exec
4087 @cindex break on fork/exec
4088 A call to @code{exec}.  This is currently only available for HP-UX
4089 and @sc{gnu}/Linux.
4090
4091 @item syscall
4092 @itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{} 
4093 @cindex break on a system call.
4094 A call to or return from a system call, a.k.a.@: @dfn{syscall}.  A
4095 syscall is a mechanism for application programs to request a service
4096 from the operating system (OS) or one of the OS system services.
4097 @value{GDBN} can catch some or all of the syscalls issued by the
4098 debuggee, and show the related information for each syscall.  If no
4099 argument is specified, calls to and returns from all system calls
4100 will be caught.
4101
4102 @var{name} can be any system call name that is valid for the
4103 underlying OS.  Just what syscalls are valid depends on the OS.  On
4104 GNU and Unix systems, you can find the full list of valid syscall
4105 names on @file{/usr/include/asm/unistd.h}.
4106
4107 @c For MS-Windows, the syscall names and the corresponding numbers
4108 @c can be found, e.g., on this URL:
4109 @c http://www.metasploit.com/users/opcode/syscalls.html
4110 @c but we don't support Windows syscalls yet.
4111
4112 Normally, @value{GDBN} knows in advance which syscalls are valid for
4113 each OS, so you can use the @value{GDBN} command-line completion
4114 facilities (@pxref{Completion,, command completion}) to list the
4115 available choices.
4116
4117 You may also specify the system call numerically.  A syscall's
4118 number is the value passed to the OS's syscall dispatcher to
4119 identify the requested service.  When you specify the syscall by its
4120 name, @value{GDBN} uses its database of syscalls to convert the name
4121 into the corresponding numeric code, but using the number directly
4122 may be useful if @value{GDBN}'s database does not have the complete
4123 list of syscalls on your system (e.g., because @value{GDBN} lags
4124 behind the OS upgrades).
4125
4126 The example below illustrates how this command works if you don't provide
4127 arguments to it:
4128
4129 @smallexample
4130 (@value{GDBP}) catch syscall
4131 Catchpoint 1 (syscall)
4132 (@value{GDBP}) r
4133 Starting program: /tmp/catch-syscall
4134
4135 Catchpoint 1 (call to syscall 'close'), \
4136            0xffffe424 in __kernel_vsyscall ()
4137 (@value{GDBP}) c
4138 Continuing.
4139
4140 Catchpoint 1 (returned from syscall 'close'), \
4141         0xffffe424 in __kernel_vsyscall ()
4142 (@value{GDBP})
4143 @end smallexample
4144
4145 Here is an example of catching a system call by name:
4146
4147 @smallexample
4148 (@value{GDBP}) catch syscall chroot
4149 Catchpoint 1 (syscall 'chroot' [61])
4150 (@value{GDBP}) r
4151 Starting program: /tmp/catch-syscall
4152
4153 Catchpoint 1 (call to syscall 'chroot'), \
4154                    0xffffe424 in __kernel_vsyscall ()
4155 (@value{GDBP}) c
4156 Continuing.
4157
4158 Catchpoint 1 (returned from syscall 'chroot'), \
4159         0xffffe424 in __kernel_vsyscall ()
4160 (@value{GDBP})
4161 @end smallexample
4162
4163 An example of specifying a system call numerically.  In the case
4164 below, the syscall number has a corresponding entry in the XML
4165 file, so @value{GDBN} finds its name and prints it:
4166
4167 @smallexample
4168 (@value{GDBP}) catch syscall 252
4169 Catchpoint 1 (syscall(s) 'exit_group')
4170 (@value{GDBP}) r
4171 Starting program: /tmp/catch-syscall
4172
4173 Catchpoint 1 (call to syscall 'exit_group'), \
4174                    0xffffe424 in __kernel_vsyscall ()
4175 (@value{GDBP}) c
4176 Continuing.
4177
4178 Program exited normally.
4179 (@value{GDBP})
4180 @end smallexample
4181
4182 However, there can be situations when there is no corresponding name
4183 in XML file for that syscall number.  In this case, @value{GDBN} prints
4184 a warning message saying that it was not able to find the syscall name,
4185 but the catchpoint will be set anyway.  See the example below:
4186
4187 @smallexample
4188 (@value{GDBP}) catch syscall 764
4189 warning: The number '764' does not represent a known syscall.
4190 Catchpoint 2 (syscall 764)
4191 (@value{GDBP})
4192 @end smallexample
4193
4194 If you configure @value{GDBN} using the @samp{--without-expat} option,
4195 it will not be able to display syscall names.  Also, if your
4196 architecture does not have an XML file describing its system calls,
4197 you will not be able to see the syscall names.  It is important to
4198 notice that these two features are used for accessing the syscall
4199 name database.  In either case, you will see a warning like this:
4200
4201 @smallexample
4202 (@value{GDBP}) catch syscall
4203 warning: Could not open "syscalls/i386-linux.xml"
4204 warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
4205 GDB will not be able to display syscall names.
4206 Catchpoint 1 (syscall)
4207 (@value{GDBP})
4208 @end smallexample
4209
4210 Of course, the file name will change depending on your architecture and system.
4211
4212 Still using the example above, you can also try to catch a syscall by its
4213 number.  In this case, you would see something like:
4214
4215 @smallexample
4216 (@value{GDBP}) catch syscall 252
4217 Catchpoint 1 (syscall(s) 252)
4218 @end smallexample
4219
4220 Again, in this case @value{GDBN} would not be able to display syscall's names.
4221
4222 @item fork
4223 A call to @code{fork}.  This is currently only available for HP-UX
4224 and @sc{gnu}/Linux.
4225
4226 @item vfork
4227 A call to @code{vfork}.  This is currently only available for HP-UX
4228 and @sc{gnu}/Linux.
4229
4230 @item load @r{[}regexp@r{]}
4231 @itemx unload @r{[}regexp@r{]}
4232 The loading or unloading of a shared library.  If @var{regexp} is
4233 given, then the catchpoint will stop only if the regular expression
4234 matches one of the affected libraries.
4235
4236 @item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]}
4237 The delivery of a signal.
4238
4239 With no arguments, this catchpoint will catch any signal that is not
4240 used internally by @value{GDBN}, specifically, all signals except
4241 @samp{SIGTRAP} and @samp{SIGINT}.
4242
4243 With the argument @samp{all}, all signals, including those used by
4244 @value{GDBN}, will be caught.  This argument cannot be used with other
4245 signal names.
4246
4247 Otherwise, the arguments are a list of signal names as given to
4248 @code{handle} (@pxref{Signals}).  Only signals specified in this list
4249 will be caught.
4250
4251 One reason that @code{catch signal} can be more useful than
4252 @code{handle} is that you can attach commands and conditions to the
4253 catchpoint.
4254
4255 When a signal is caught by a catchpoint, the signal's @code{stop} and
4256 @code{print} settings, as specified by @code{handle}, are ignored.
4257 However, whether the signal is still delivered to the inferior depends
4258 on the @code{pass} setting; this can be changed in the catchpoint's
4259 commands.
4260
4261 @end table
4262
4263 @item tcatch @var{event}
4264 Set a catchpoint that is enabled only for one stop.  The catchpoint is
4265 automatically deleted after the first time the event is caught.
4266
4267 @end table
4268
4269 Use the @code{info break} command to list the current catchpoints.
4270
4271 There are currently some limitations to C@t{++} exception handling
4272 (@code{catch throw} and @code{catch catch}) in @value{GDBN}:
4273
4274 @itemize @bullet
4275 @item
4276 If you call a function interactively, @value{GDBN} normally returns
4277 control to you when the function has finished executing.  If the call
4278 raises an exception, however, the call may bypass the mechanism that
4279 returns control to you and cause your program either to abort or to
4280 simply continue running until it hits a breakpoint, catches a signal
4281 that @value{GDBN} is listening for, or exits.  This is the case even if
4282 you set a catchpoint for the exception; catchpoints on exceptions are
4283 disabled within interactive calls.
4284
4285 @item
4286 You cannot raise an exception interactively.
4287
4288 @item
4289 You cannot install an exception handler interactively.
4290 @end itemize
4291
4292 @cindex raise exceptions
4293 Sometimes @code{catch} is not the best way to debug exception handling:
4294 if you need to know exactly where an exception is raised, it is better to
4295 stop @emph{before} the exception handler is called, since that way you
4296 can see the stack before any unwinding takes place.  If you set a
4297 breakpoint in an exception handler instead, it may not be easy to find
4298 out where the exception was raised.
4299
4300 To stop just before an exception handler is called, you need some
4301 knowledge of the implementation.  In the case of @sc{gnu} C@t{++}, exceptions are
4302 raised by calling a library function named @code{__raise_exception}
4303 which has the following ANSI C interface:
4304
4305 @smallexample
4306     /* @var{addr} is where the exception identifier is stored.
4307        @var{id} is the exception identifier.  */
4308     void __raise_exception (void **addr, void *id);
4309 @end smallexample
4310
4311 @noindent
4312 To make the debugger catch all exceptions before any stack
4313 unwinding takes place, set a breakpoint on @code{__raise_exception}
4314 (@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Exceptions}).
4315
4316 With a conditional breakpoint (@pxref{Conditions, ,Break Conditions})
4317 that depends on the value of @var{id}, you can stop your program when
4318 a specific exception is raised.  You can use multiple conditional
4319 breakpoints to stop your program when any of a number of exceptions are
4320 raised.
4321
4322
4323 @node Delete Breaks
4324 @subsection Deleting Breakpoints
4325
4326 @cindex clearing breakpoints, watchpoints, catchpoints
4327 @cindex deleting breakpoints, watchpoints, catchpoints
4328 It is often necessary to eliminate a breakpoint, watchpoint, or
4329 catchpoint once it has done its job and you no longer want your program
4330 to stop there.  This is called @dfn{deleting} the breakpoint.  A
4331 breakpoint that has been deleted no longer exists; it is forgotten.
4332
4333 With the @code{clear} command you can delete breakpoints according to
4334 where they are in your program.  With the @code{delete} command you can
4335 delete individual breakpoints, watchpoints, or catchpoints by specifying
4336 their breakpoint numbers.
4337
4338 It is not necessary to delete a breakpoint to proceed past it.  @value{GDBN}
4339 automatically ignores breakpoints on the first instruction to be executed
4340 when you continue execution without changing the execution address.
4341
4342 @table @code
4343 @kindex clear
4344 @item clear
4345 Delete any breakpoints at the next instruction to be executed in the
4346 selected stack frame (@pxref{Selection, ,Selecting a Frame}).  When
4347 the innermost frame is selected, this is a good way to delete a
4348 breakpoint where your program just stopped.
4349
4350 @item clear @var{location}
4351 Delete any breakpoints set at the specified @var{location}.
4352 @xref{Specify Location}, for the various forms of @var{location}; the
4353 most useful ones are listed below:
4354
4355 @table @code
4356 @item clear @var{function}
4357 @itemx clear @var{filename}:@var{function}
4358 Delete any breakpoints set at entry to the named @var{function}.
4359
4360 @item clear @var{linenum}
4361 @itemx clear @var{filename}:@var{linenum}
4362 Delete any breakpoints set at or within the code of the specified
4363 @var{linenum} of the specified @var{filename}.
4364 @end table
4365
4366 @cindex delete breakpoints
4367 @kindex delete
4368 @kindex d @r{(@code{delete})}
4369 @item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
4370 Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
4371 ranges specified as arguments.  If no argument is specified, delete all
4372 breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
4373 confirm off}).  You can abbreviate this command as @code{d}.
4374 @end table
4375
4376 @node Disabling
4377 @subsection Disabling Breakpoints
4378
4379 @cindex enable/disable a breakpoint
4380 Rather than deleting a breakpoint, watchpoint, or catchpoint, you might
4381 prefer to @dfn{disable} it.  This makes the breakpoint inoperative as if
4382 it had been deleted, but remembers the information on the breakpoint so
4383 that you can @dfn{enable} it again later.
4384
4385 You disable and enable breakpoints, watchpoints, and catchpoints with
4386 the @code{enable} and @code{disable} commands, optionally specifying
4387 one or more breakpoint numbers as arguments.  Use @code{info break} to
4388 print a list of all breakpoints, watchpoints, and catchpoints if you
4389 do not know which numbers to use.
4390
4391 Disabling and enabling a breakpoint that has multiple locations
4392 affects all of its locations.
4393
4394 A breakpoint, watchpoint, or catchpoint can have any of several
4395 different states of enablement:
4396
4397 @itemize @bullet
4398 @item
4399 Enabled.  The breakpoint stops your program.  A breakpoint set
4400 with the @code{break} command starts out in this state.
4401 @item
4402 Disabled.  The breakpoint has no effect on your program.
4403 @item
4404 Enabled once.  The breakpoint stops your program, but then becomes
4405 disabled.
4406 @item
4407 Enabled for a count.  The breakpoint stops your program for the next
4408 N times, then becomes disabled.
4409 @item
4410 Enabled for deletion.  The breakpoint stops your program, but
4411 immediately after it does so it is deleted permanently.  A breakpoint
4412 set with the @code{tbreak} command starts out in this state.
4413 @end itemize