Upgrade GDB from 7.4.1 to 7.6.1 on the vendor branch
[dragonfly.git] / contrib / gdb-7 / gdb / doc / gdb.texinfo
CommitLineData
5796c8dc 1\input texinfo @c -*-texinfo-*-
ef5ccd6c 2@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
5796c8dc
SS
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
ef5ccd6c
JM
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
5796c8dc
SS
27
28@c readline appendices use @vindex, @findex and @ftable,
29@c annotate.texi and gdbmi use @findex.
ef5ccd6c 30@syncodeindex vr fn
5796c8dc
SS
31
32@c !!set GDB manual's edition---not the same as GDB version!
33@c This is updated by GNU Press.
a45ae5f8 34@set EDITION Tenth
5796c8dc
SS
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
ef5ccd6c 49Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
5796c8dc
SS
50
51Permission is granted to copy, distribute and/or modify this document
cf7f2e2d 52under the terms of the GNU Free Documentation License, Version 1.3 or
5796c8dc
SS
53any later version published by the Free Software Foundation; with the
54Invariant Sections being ``Free Software'' and ``Free Software Needs
55Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
56and 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
59this GNU Manual. Buying copies from GNU Press supports the FSF in
60developing GNU and promoting software freedom.''
61@end copying
62
63@ifnottex
64This file documents the @sc{gnu} debugger @value{GDBN}.
65
66This 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
71Version @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
96Published by the Free Software Foundation @*
9751 Franklin Street, Fifth Floor,
98Boston, MA 02110-1301, USA@*
a45ae5f8 99ISBN 978-0-9831592-3-0 @*
5796c8dc
SS
100
101@insertcopying
5796c8dc
SS
102@end titlepage
103@page
104
105@ifnottex
106@node Top, Summary, (dir), (dir)
107
108@top Debugging with @value{GDBN}
109
110This file describes @value{GDBN}, the @sc{gnu} symbolic debugger.
111
112This is the @value{EDITION} Edition, for @value{GDBN}
113@ifset VERSION_PACKAGE
114@value{VERSION_PACKAGE}
115@end ifset
116Version @value{GDBVN}.
117
ef5ccd6c 118Copyright (C) 1988-2013 Free Software Foundation, Inc.
5796c8dc
SS
119
120This edition of the GDB manual is dedicated to the memory of Fred
121Fish. Fred was a long-standing contributor to GDB and to Free
122software 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.
ef5ccd6c 158* In-Process Agent:: In-Process Agent
5796c8dc
SS
159
160* GDB Bugs:: Reporting bugs in @value{GDBN}
161
c50c785c
JM
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
5796c8dc
SS
167* Command Line Editing:: Command Line Editing
168* Using History Interactively:: Using History Interactively
c50c785c
JM
169@end ifclear
170* In Memoriam:: In Memoriam
5796c8dc
SS
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
cf7f2e2d 180* Trace File Format:: GDB trace file format
a45ae5f8 181* Index Section Format:: .gdb_index section format
5796c8dc
SS
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
ef5ccd6c
JM
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
5796c8dc
SS
188@end menu
189
190@end ifnottex
191
192@contents
193
194@node Summary
195@unnumbered Summary of @value{GDBN}
196
197The purpose of a debugger such as @value{GDBN} is to allow you to see what is
198going on ``inside'' another program while it executes---or what another
199program was doing at the moment it crashed.
200
201@value{GDBN} can do four main kinds of things (plus other things in support of
202these) to help you catch bugs in the act:
203
204@itemize @bullet
205@item
206Start your program, specifying anything that might affect its behavior.
207
208@item
209Make your program stop on specified conditions.
210
211@item
212Examine what has happened, when your program has stopped.
213
214@item
215Change things in your program, so you can experiment with correcting the
216effects of one bug and go on to learn about another.
217@end itemize
218
219You can use @value{GDBN} to debug programs written in C and C@t{++}.
220For more information, see @ref{Supported Languages,,Supported Languages}.
221For more information, see @ref{C,,C and C++}.
222
cf7f2e2d
JM
223Support for D is partial. For information on D, see
224@ref{D,,D}.
225
5796c8dc
SS
226@cindex Modula-2
227Support for Modula-2 is partial. For information on Modula-2, see
228@ref{Modula-2,,Modula-2}.
229
c50c785c
JM
230Support for OpenCL C is partial. For information on OpenCL C, see
231@ref{OpenCL C,,OpenCL C}.
232
5796c8dc
SS
233@cindex Pascal
234Debugging Pascal programs which use sets, subranges, file variables, or
235nested functions does not currently work. @value{GDBN} does not support
236entering expressions, printing values, or similar features using Pascal
237syntax.
238
239@cindex Fortran
240@value{GDBN} can be used to debug programs written in Fortran, although
241it may be necessary to refer to some variables with a trailing
242underscore.
243
244@value{GDBN} can be used to debug programs written in Objective-C,
245using either the Apple/NeXT or the GNU Objective-C runtime.
246
247@menu
248* Free Software:: Freely redistributable software
ef5ccd6c 249* Free Documentation:: Free Software Needs Free Documentation
5796c8dc
SS
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}
257General Public License
258(GPL). The GPL gives you the freedom to copy or adapt a licensed
259program---but every person getting a copy also gets with it the
260freedom to modify that copy (which means that they must get access to
261the source code), and the freedom to distribute further copies.
262Typical software companies use copyrights to limit your freedoms; the
263Free Software Foundation uses the GPL to preserve these freedoms.
264
265Fundamentally, the General Public License is a license which says that
266you have these freedoms and that you cannot take these freedoms away
267from anyone else.
268
ef5ccd6c 269@node Free Documentation
5796c8dc
SS
270@unnumberedsec Free Software Needs Free Documentation
271
272The biggest deficiency in the free software community today is not in
273the software---it is the lack of good free documentation that we can
274include with the free software. Many of our most important
275programs do not come with free reference manuals and free introductory
276texts. Documentation is an essential part of any software package;
277when an important free software package does not come with a free
278manual and a free tutorial, that is a major gap. We have many such
279gaps today.
280
281Consider Perl, for instance. The tutorial manuals that people
282normally use are non-free. How did this come about? Because the
283authors of those manuals published them with restrictive terms---no
284copying, no modification, source files not available---which exclude
285them from the free software world.
286
287That wasn't the first time this sort of thing happened, and it was far
288from the last. Many times we have heard a GNU user eagerly describe a
289manual that he is writing, his intended contribution to the community,
290only to learn that he had ruined everything by signing a publication
291contract to make it non-free.
292
293Free documentation, like free software, is a matter of freedom, not
294price. The problem with the non-free manual is not that publishers
295charge a price for printed copies---that in itself is fine. (The Free
296Software Foundation sells printed copies of manuals, too.) The
297problem is the restrictions on the use of the manual. Free manuals
298are available in source code form, and give you permission to copy and
299modify. Non-free manuals do not allow this.
300
301The criteria of freedom for a free manual are roughly the same as for
302free software. Redistribution (including the normal kinds of
303commercial redistribution) must be permitted, so that the manual can
304accompany every copy of the program, both on-line and on paper.
305
306Permission for modification of the technical content is crucial too.
307When people modify the software, adding or changing features, if they
308are conscientious they will change the manual too---so they can
309provide accurate and clear documentation for the modified program. A
310manual that leaves you no choice but to write a new manual to document
311a changed version of the program is not really available to our
312community.
313
314Some kinds of limits on the way modification is handled are
315acceptable. For example, requirements to preserve the original
316author's copyright notice, the distribution terms, or the list of
317authors, are ok. It is also no problem to require modified versions
318to include notice that they were modified. Even entire sections that
319may not be deleted or changed are acceptable, as long as they deal
320with nontechnical topics (like this one). These kinds of restrictions
321are acceptable because they don't obstruct the community's normal use
322of the manual.
323
324However, it must be possible to modify all the @emph{technical}
325content of the manual, and then distribute the result in all the usual
326media, through all the usual channels. Otherwise, the restrictions
327obstruct the use of the manual, it is not free, and we need another
328manual to replace it.
329
330Please spread the word about this issue. Our community continues to
331lose manuals to proprietary publishing. If we spread the word that
332free software needs free reference manuals and free tutorials, perhaps
333the next person who wants to contribute by writing documentation will
334realize, before it is too late, that only free manuals contribute to
335the free software community.
336
337If you are writing documentation, please insist on publishing it under
338the GNU Free Documentation License or another free documentation
339license. Remember that this decision requires your approval---you
340don't have to let the publisher decide. Some commercial publishers
341will use a free license if you insist, but they will not propose the
342option; it is up to you to raise the issue and say firmly that this is
343what you want. If the publisher you are dealing with refuses, please
344try other publishers. If you're not sure whether a proposed license
345is free, write to @email{licensing@@gnu.org}.
346
347You can encourage commercial publishers to sell more free, copylefted
348manuals and tutorials by buying them, and particularly by buying
349copies from the publishers that paid for their writing or for major
350improvements. Meanwhile, try to avoid buying non-free documentation
351at all. Check the distribution terms of a manual before you buy it,
352and insist that whoever seeks your business must respect your freedom.
353Check the history of the book, and try to reward the publishers that
354have paid or pay the authors to work on it.
355
356The Free Software Foundation maintains a list of free documentation
357published 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
363Richard Stallman was the original author of @value{GDBN}, and of many
364other @sc{gnu} programs. Many others have contributed to its
365development. This section attempts to credit major contributors. One
366of the virtues of free software is that everyone is free to contribute
367to it; with regret, we cannot actually acknowledge everyone here. The
368file @file{ChangeLog} in the @value{GDBN} distribution approximates a
369blow-by-blow account.
370
371Changes 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
375or your friends (or enemies, to be evenhanded) have been unfairly
376omitted from this list, we would like to add your names!
377@end quotation
378
379So that they may not regard their many labors as thankless, we
380particularly thank those who shepherded @value{GDBN} through major
381releases:
382Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
383Jim Blandy (release 4.18);
384Jason Molenda (release 4.17);
385Stan Shebs (release 4.14);
386Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9);
387Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4);
388John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9);
389Jim Kingdon (releases 3.5, 3.4, and 3.3);
390and Randy Smith (releases 3.2, 3.1, and 3.0).
391
392Richard Stallman, assisted at various times by Peter TerMaat, Chris
393Hanson, and Richard Mlynarik, handled releases through 2.8.
394
395Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support
396in @value{GDBN}, with significant additional contributions from Per
397Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++}
398demangler. Early work on C@t{++} was by Peter TerMaat (who also did
399much general update work leading to release 3.0).
400
401@value{GDBN} uses the BFD subroutine library to examine multiple
402object-file formats; BFD was a joint project of David V.
403Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
404
405David Johnson wrote the original COFF support; Pace Willison did
406the original support for encapsulated COFF.
407
408Brent Benson of Harris Computer Systems contributed DWARF 2 support.
409
410Adam de Boor and Bradley Davis contributed the ISI Optimum V support.
411Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS
412support.
413Jean-Daniel Fekete contributed Sun 386i support.
414Chris Hanson improved the HP9000 support.
415Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support.
416David Johnson contributed Encore Umax support.
417Jyrki Kuoppala contributed Altos 3068 support.
418Jeff Law contributed HP PA and SOM support.
419Keith Packard contributed NS32K support.
420Doug Rabson contributed Acorn Risc Machine support.
421Bob Rusk contributed Harris Nighthawk CX-UX support.
422Chris Smith contributed Convex support (and Fortran debugging).
423Jonathan Stone contributed Pyramid support.
424Michael Tiemann contributed SPARC support.
425Tim Tucker contributed support for the Gould NP1 and Gould Powernode.
426Pace Willison contributed Intel 386 support.
427Jay Vosburgh contributed Symmetry support.
428Marko Mlinar contributed OpenRISC 1000 support.
429
430Andreas Schwab contributed M68K @sc{gnu}/Linux support.
431
432Rich Schaefer and Peter Schauer helped with support of SunOS shared
433libraries.
434
435Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree
436about several machine instruction sets.
437
438Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop
439remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM
440contributed remote debugging modules for the i960, VxWorks, A29K UDI,
441and RDI targets, respectively.
442
443Brian Fox is the author of the readline libraries providing
444command-line editing and command history.
445
446Andrew Beers of SUNY Buffalo wrote the language-switching code, the
447Modula-2 support, and contributed the Languages chapter of this manual.
448
449Fred Fish wrote most of the support for Unix System Vr4.
450He also enhanced the command-completion support to cover C@t{++} overloaded
451symbols.
452
453Hitachi America (now Renesas America), Ltd. sponsored the support for
454H8/300, H8/500, and Super-H processors.
455
456NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
457
458Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D
459processors.
460
461Toshiba sponsored the support for the TX39 Mips processor.
462
463Matsushita sponsored the support for the MN10200 and MN10300 processors.
464
465Fujitsu sponsored the support for SPARClite and FR30 processors.
466
467Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware
468watchpoints.
469
470Michael Snyder added support for tracepoints.
471
472Stu Grossman wrote gdbserver.
473
474Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made
475nearly innumerable bug fixes and cleanups throughout @value{GDBN}.
476
477The following people at the Hewlett-Packard Company contributed
478support 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{++}
480compiler, and the Text User Interface (nee Terminal User Interface):
481Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann,
482Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase
483provided HP-specific information in this manual.
484
485DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project.
486Robert Hoehne made significant contributions to the DJGPP port.
487
488Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its
489development since 1991. Cygnus engineers who have worked on @value{GDBN}
490fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin
491Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim
492Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler,
493Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek
494Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In
495addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton,
496JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug
497Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff
498Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner,
499Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin
500Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela
501Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David
502Zuhn have made contributions both large and small.
503
504Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for
505Cygnus Solutions, implemented the original @sc{gdb/mi} interface.
506
507Jim Blandy added support for preprocessor macros, while working for Red
508Hat.
509
510Andrew Cagney designed @value{GDBN}'s architecture vector. Many
511people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick
512Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei
513Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason
514Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped
515with the migration of old architectures to this new framework.
516
517Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s
518unwinder framework, this consisting of a fresh new design featuring
519frame IDs, independent frame sniffers, and the sentinel frame. Mark
520Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the
521libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and
522trad unwinders. The architecture-specific changes, each involving a
523complete rewrite of the architecture's frame code, were carried out by
524Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane
525Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel
526Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei
527Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich
528Weigand.
529
530Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from
531Tensilica, Inc.@: contributed support for Xtensa processors. Others
532who have worked on the Xtensa port of @value{GDBN} in the past include
533Steve Tjiang, John Newlin, and Scott Foehner.
534
cf7f2e2d
JM
535Michael Eager and staff of Xilinx, Inc., contributed support for the
536Xilinx MicroBlaze architecture.
537
5796c8dc
SS
538@node Sample Session
539@chapter A Sample @value{GDBN} Session
540
541You can use this manual at your leisure to read all about @value{GDBN}.
542However, a handful of commands are enough to get started using the
543debugger. This chapter illustrates those commands.
544
545@iftex
546In this sample session, we emphasize user input like this: @b{input},
547to 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
553One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro
554processor) exhibits the following bug: sometimes, when we change its
555quote strings from the default, the commands used to capture one macro
556definition within another stop working. In the following short @code{m4}
557session, we define a macro @code{foo} which expands to @code{0000}; we
558then use the @code{m4} built-in @code{defn} to define @code{bar} as the
559same thing. However, when we change the open quote string to
560@code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same
561procedure 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}
5690000
570@b{define(bar,defn(`foo'))}
571
572@b{bar}
5730000
574@b{changequote(<QUOTE>,<UNQUOTE>)}
575
576@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
577@b{baz}
578@b{Ctrl-d}
579m4: End of input: 0: fatal error: EOF in string
580@end smallexample
581
582@noindent
583Let 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.
592There 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
601rest when needed; as a result, the first prompt comes up very quickly.
602We now tell @value{GDBN} to use a narrower display width than usual, so
603that examples fit in this manual.
604
605@smallexample
606(@value{GDBP}) @b{set width 70}
607@end smallexample
608
609@noindent
610We need to see how the @code{m4} built-in @code{changequote} works.
611Having 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}
617Breakpoint 1 at 0x62f4: file builtin.c, line 879.
618@end smallexample
619
620@noindent
621Using the @code{run} command, we start @code{m4} running under @value{GDBN}
622control; as long as control does not reach the @code{m4_changequote}
623subroutine, the program runs as usual:
624
625@smallexample
626(@value{GDBP}) @b{run}
627Starting program: /work/Editorial/gdb/gnu/m4/m4
628@b{define(foo,0000)}
629
630@b{foo}
6310000
632@end smallexample
633
634@noindent
635To trigger the breakpoint, we call @code{changequote}. @value{GDBN}
636suspends execution of @code{m4}, displaying information about the
637context where it stops.
638
639@smallexample
640@b{changequote(<QUOTE>,<UNQUOTE>)}
641
642Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
643 at builtin.c:879
644879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))
645@end smallexample
646
647@noindent
648Now we use the command @code{n} (@code{next}) to advance execution to
649the next line of the current function.
650
651@smallexample
652(@value{GDBP}) @b{n}
653882 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
659by 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}
661subroutine, so it steps into @code{set_quotes}.
662
663@smallexample
664(@value{GDBP}) @b{s}
665set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
666 at input.c:530
667530 if (lquote != def_lquote)
668@end smallexample
669
670@noindent
671The display that shows the subroutine where @code{m4} is now
672suspended (and its arguments) is called a stack frame display. It
673shows a summary of the stack. We can use the @code{backtrace}
674command (which can also be spelled @code{bt}), to see where we are
675in the stack as a whole: the @code{backtrace} command displays a
676stack 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
692We step through a few more lines to see what happens. The first two
693times, we can use @samp{s}; the next two times we use @code{n} to avoid
694falling into the @code{xstrdup} subroutine.
695
696@smallexample
697(@value{GDBP}) @b{s}
6980x3b5c 532 if (rquote != def_rquote)
699(@value{GDBP}) @b{s}
7000x3b80 535 lquote = (lq == nil || *lq == '\0') ? \
701def_lquote : xstrdup(lq);
702(@value{GDBP}) @b{n}
703536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
704 : xstrdup(rq);
705(@value{GDBP}) @b{n}
706538 len_lquote = strlen(rquote);
707@end smallexample
708
709@noindent
710The 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
712and 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.
724To look at some context, we can display ten lines of source
725surrounding the current line with the @code{l} (@code{list}) command.
726
727@smallexample
728(@value{GDBP}) @b{l}
729533 xfree(rquote);
730534
731535 lquote = (lq == nil || *lq == '\0') ? def_lquote\
732 : xstrdup (lq);
733536 rquote = (rq == nil || *rq == '\0') ? def_rquote\
734 : xstrdup (rq);
735537
736538 len_lquote = strlen(rquote);
737539 len_rquote = strlen(lquote);
738540 @}
739541
740542 void
741@end smallexample
742
743@noindent
744Let 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}
749539 len_rquote = strlen(lquote);
750(@value{GDBP}) @b{n}
751540 @}
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
759That 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
762the @code{p} command, since it can print the value of
763any expression---and that expression can include subroutine calls and
764assignments.
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
774Is 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
776executing with the @code{c} (@code{continue}) command, and then try the
777example that caused trouble initially:
778
779@smallexample
780(@value{GDBP}) @b{c}
781Continuing.
782
783@b{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
784
785baz
7860000
787@end smallexample
788
789@noindent
790Success! The new quotes now work just as well as the default ones. The
791problem seems to have been just the two typos defining the wrong
792lengths. We allow @code{m4} exit by giving it an EOF as input:
793
794@smallexample
795@b{Ctrl-d}
796Program exited normally.
797@end smallexample
798
799@noindent
800The message @samp{Program exited normally.} is from @value{GDBN}; it
801indicates @code{m4} has finished executing. We can end our @value{GDBN}
802session 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
811This chapter discusses how to start @value{GDBN}, and how to get out of it.
812The essentials are:
813@itemize @bullet
814@item
815type @samp{@value{GDBP}} to start @value{GDBN}.
816@item
817type @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
830Invoke @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
833You can also run @code{@value{GDBP}} with a variety of arguments and options,
834to specify more of your debugging environment at the outset.
835
836The command-line options described here are designed
837to cover a variety of situations; in some environments, some of these
838options may effectively be unavailable.
839
840The most usual way to start @value{GDBN} is with one argument,
841specifying an executable program:
842
843@smallexample
844@value{GDBP} @var{program}
845@end smallexample
846
847@noindent
848You can also start with both an executable program and a core file
849specified:
850
851@smallexample
852@value{GDBP} @var{program} @var{core}
853@end smallexample
854
855You can, instead, specify a process ID as a second argument, if you want
856to debug a running process:
857
858@smallexample
859@value{GDBP} @var{program} 1234
860@end smallexample
861
862@noindent
863would attach @value{GDBN} to process @code{1234} (unless you also have a file
864named @file{1234}; @value{GDBN} does check for a core file first).
865
866Taking advantage of the second command-line argument requires a fairly
867complete operating system; when you use @value{GDBN} as a remote
868debugger 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}
870will warn you if it is unable to attach or to read core dumps.
871
872You can optionally have @code{@value{GDBP}} pass any arguments after the
873executable file to the inferior using @code{--args}. This option stops
874option processing.
875@smallexample
876@value{GDBP} --args gcc -O2 -c foo.c
877@end smallexample
878This 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
881You 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
889You can further control how @value{GDBN} starts up by using command-line
890options. @value{GDBN} itself can remind you of the options available.
891
892@noindent
893Type
894
895@smallexample
896@value{GDBP} -help
897@end smallexample
898
899@noindent
900to display all available options and briefly describe their use
901(@samp{@value{GDBP} -h} is a shorter equivalent).
902
903All options and command line arguments you give are processed
904in 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
917When @value{GDBN} starts, it reads any arguments other than options as
918specifying an executable file and core file (or process ID). This is
919the same as if the arguments were specified by the @samp{-se} and
920@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the
921first argument that does not have an associated option flag as
922equivalent to the @samp{-se} option followed by that argument; and the
923second argument that does not have an associated option flag, if any, as
924equivalent to the @samp{-c}/@samp{-p} option followed by that argument.)
925If the second argument begins with a decimal digit, @value{GDBN} will
926first attempt to attach to it as a process, and if that fails, attempt
927to open it as a corefile. If you have a corefile whose name begins with
928a digit, you can prevent @value{GDBN} from treating it as a pid by
929prefixing it with @file{./}, e.g.@: @file{./12345}.
930
931If @value{GDBN} has not been configured to included core file support,
932such as for most embedded targets, then it will complain about a second
933argument and ignore it.
934
935Many options have both long and short forms; both are shown in the
936following list. @value{GDBN} also recognizes the long forms if you truncate
937them, so long as enough of the option is present to be unambiguous.
938(If you prefer, you can flag option arguments with @samp{--} rather
939than @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}
950Read 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}
956Use file @var{file} as the executable file to execute when appropriate,
957and for examining pure data in conjunction with a core dump.
958
959@item -se @var{file}
960@cindex @code{--se}
961Read symbol table from file @var{file} and use it as the executable
962file.
963
964@item -core @var{file}
965@itemx -c @var{file}
966@cindex @code{--core}
967@cindex @code{-c}
968Use 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}
974Connect 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}
cf7f2e2d
JM
980Execute commands from file @var{file}. The contents of this file is
981evaluated exactly as the @code{source} command would.
982@xref{Command Files,, Command files}.
5796c8dc
SS
983
984@item -eval-command @var{command}
985@itemx -ex @var{command}
986@cindex @code{--eval-command}
987@cindex @code{-ex}
988Execute a single @value{GDBN} command.
989
990This option may be used multiple times to call multiple commands. It may
991also 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
ef5ccd6c
JM
998@item -init-command @var{file}
999@itemx -ix @var{file}
1000@cindex @code{--init-command}
1001@cindex @code{-ix}
1002Execute commands from file @var{file} before loading the inferior (but
1003after 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}
1010Execute a single @value{GDBN} command before loading the inferior (but
1011after loading gdbinit files).
1012@xref{Startup}.
1013
5796c8dc
SS
1014@item -directory @var{directory}
1015@itemx -d @var{directory}
1016@cindex @code{--directory}
1017@cindex @code{-d}
1018Add @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}
1024Read each symbol file's entire symbol table immediately, rather than
1025the default, which is to read it incrementally as it is needed.
1026This makes startup slower, but makes future operations faster.
1027
1028@end table
1029
1030@node Mode Options
1031@subsection Choosing Modes
1032
1033You can run @value{GDBN} in various alternative modes---for example, in
1034batch mode or quiet mode.
1035
1036@table @code
ef5ccd6c 1037@anchor{-nx}
5796c8dc
SS
1038@item -nx
1039@itemx -n
1040@cindex @code{--nx}
1041@cindex @code{-n}
ef5ccd6c
JM
1042Do not execute commands found in any initialization file.
1043There are three init files, loaded in the following order:
1044
1045@table @code
1046@item @file{system.gdbinit}
1047This is the system-wide init file.
1048Its location is specified with the @code{--with-system-gdbinit}
1049configure option (@pxref{System-wide configuration}).
1050It is loaded first when @value{GDBN} starts, before command line options
1051have been processed.
1052@item @file{~/.gdbinit}
1053This is the init file in your home directory.
1054It is loaded next, after @file{system.gdbinit}, and before
1055command options have been processed.
1056@item @file{./.gdbinit}
1057This is the init file in the current directory.
1058It 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
1063For further documentation on startup processing, @xref{Startup}.
1064For documentation on how to write command files,
1065@xref{Command Files,,Command Files}.
1066
1067@anchor{-nh}
1068@item -nh
1069@cindex @code{--nh}
1070Do not execute commands found in @file{~/.gdbinit}, the init file
1071in your home directory.
1072@xref{Startup}.
5796c8dc
SS
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
1081messages are also suppressed in batch mode.
1082
1083@item -batch
1084@cindex @code{--batch}
1085Run in batch mode. Exit with status @code{0} after processing all the
1086command files specified with @samp{-x} (and all commands from
1087initialization files, if not inhibited with @samp{-n}). Exit with
1088nonzero status if an error occurs in executing the @value{GDBN} commands
cf7f2e2d
JM
1089in the command files. Batch mode also disables pagination, sets unlimited
1090terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm
1091off} were in effect (@pxref{Messages/Warnings}).
5796c8dc
SS
1092
1093Batch mode may be useful for running @value{GDBN} as a filter, for
1094example to download and run a program on another computer; in order to
1095make this more useful, the message
1096
1097@smallexample
1098Program 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
1104mode.
1105
1106@item -batch-silent
1107@cindex @code{--batch-silent}
1108Run in batch mode exactly like @samp{-batch}, but totally silently. All
1109@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
1110unaffected). This is much quieter than @samp{-silent} and would be useless
1111for an interactive session.
1112
1113This is particularly useful when using targets that give @samp{Loading section}
1114messages, for example.
1115
1116Note that targets that give their output via @value{GDBN}, as opposed to
1117writing directly to @code{stdout}, will also be made silent.
1118
1119@item -return-child-result
1120@cindex @code{--return-child-result}
1121The return code from @value{GDBN} will be the return code from the child
1122process (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
1127internal error. In this case the exit code is the same as it would have been
1128without @samp{-return-child-result}.
1129@item
1130The user quits with an explicit value. E.g., @samp{quit 1}.
1131@item
1132The child process never runs, or is not allowed to terminate, in which case
1133the exit code will be -1.
1134@end itemize
1135
1136This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
1137when @value{GDBN} is being used as a remote program loader or simulator
1138interface.
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
1146interface. 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}
1152If @value{GDBN} includes a GUI, then this option requires it to be
1153used if possible.
1154
1155@item -cd @var{directory}
1156@cindex @code{--cd}
1157Run @value{GDBN} using @var{directory} as its working directory,
1158instead of the current directory.
1159
c50c785c
JM
1160@item -data-directory @var{directory}
1161@cindex @code{--data-directory}
1162Run @value{GDBN} using @var{directory} as its data directory.
1163The data directory is where @value{GDBN} searches for its
1164auxiliary files. @xref{Data Files}.
1165
5796c8dc
SS
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
1171subprocess. It tells @value{GDBN} to output the full file name and line
1172number in a standard, recognizable fashion each time a stack frame is
1173displayed (which includes each time your program stops). This
1174recognizable format looks like two @samp{\032} characters, followed by
1175the file name, line number and character position separated by colons,
1176and 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
1178frame.
1179
5796c8dc
SS
1180@item -annotate @var{level}
1181@cindex @code{--annotate}
1182This option sets the @dfn{annotation level} inside @value{GDBN}. Its
1183effect is identical to using @samp{set annotate @var{level}}
1184(@pxref{Annotations}). The annotation @var{level} controls how much
1185information @value{GDBN} prints together with its prompt, values of
1186expressions, source lines, and other types of output. Level 0 is the
1187normal, 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
1189that control @value{GDBN}, and level 2 has been deprecated.
1190
1191The annotation mechanism has largely been superseded by @sc{gdb/mi}
1192(@pxref{GDB/MI}).
1193
1194@item --args
1195@cindex @code{--args}
1196Change interpretation of command line so that arguments following the
1197executable file are passed as command line arguments to the inferior.
1198This option stops option processing.
1199
1200@item -baud @var{bps}
1201@itemx -b @var{bps}
1202@cindex @code{--baud}
1203@cindex @code{-b}
1204Set the line speed (baud rate or bits per second) of any serial
1205interface used by @value{GDBN} for remote debugging.
1206
1207@item -l @var{timeout}
1208@cindex @code{-l}
1209Set the timeout (in seconds) of any communication used by @value{GDBN}
1210for remote debugging.
1211
1212@item -tty @var{device}
1213@itemx -t @var{device}
1214@cindex @code{--tty}
1215@cindex @code{-t}
1216Run 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}
1222Activate the @dfn{Text User Interface} when starting. The Text User
1223Interface manages several text windows on the terminal, showing
1224source, assembly, registers and @value{GDBN} command outputs
ef5ccd6c
JM
1225(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this
1226option if you run @value{GDBN} from Emacs (@pxref{Emacs, ,
1227Using @value{GDBN} under @sc{gnu} Emacs}).
5796c8dc
SS
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}
1238Use the interpreter @var{interp} for interface with the controlling
1239program or device. This option is meant to be set by programs which
1240communicate 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, ,
1245The @sc{gdb/mi} Interface}) included since @value{GDBN} version 6.0. The
1246previous @sc{gdb/mi} interface, included in @value{GDBN} version 5.3 and
1247selected with @samp{--interpreter=mi1}, is deprecated. Earlier
1248@sc{gdb/mi} interfaces are no longer supported.
1249
1250@item -write
1251@cindex @code{--write}
1252Open the executable and core files for both reading and writing. This
1253is equivalent to the @samp{set write on} command inside @value{GDBN}
1254(@pxref{Patching}).
1255
1256@item -statistics
1257@cindex @code{--statistics}
1258This option causes @value{GDBN} to print statistics about time and
1259memory usage after it completes each command and returns to the prompt.
1260
1261@item -version
1262@cindex @code{--version}
1263This option causes @value{GDBN} to print its version number and
1264no-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
1272Here's the description of what @value{GDBN} does during session startup:
1273
1274@enumerate
1275@item
1276Sets up the command interpreter as specified by the command line
1277(@pxref{Mode Options, interpreter}).
1278
1279@item
1280@cindex init file
1281Reads the system-wide @dfn{init file} (if @option{--with-system-gdbinit} was
1282used when building @value{GDBN}; @pxref{System-wide configuration,
1283 ,System-wide configuration and settings}) and executes all the commands in
1284that file.
1285
ef5ccd6c 1286@anchor{Home Directory Init File}
5796c8dc
SS
1287@item
1288Reads the init file (if any) in your home directory@footnote{On
1289DOS/Windows systems, the home directory is the one pointed to by the
1290@code{HOME} environment variable.} and executes all the commands in
1291that file.
1292
ef5ccd6c
JM
1293@anchor{Option -init-eval-command}
1294@item
1295Executes 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
1298settings before @value{GDBN} init files get executed and before inferior
1299gets loaded.
1300
5796c8dc
SS
1301@item
1302Processes command line options and operands.
1303
ef5ccd6c 1304@anchor{Init File in the Current Directory during Startup}
5796c8dc
SS
1305@item
1306Reads and executes the commands from init file (if any) in the current
ef5ccd6c
JM
1307working directory as long as @samp{set auto-load local-gdbinit} is set to
1308@samp{on} (@pxref{Init File in the Current Directory}).
1309This is only done if the current directory is
5796c8dc
SS
1310different from your home directory. Thus, you can have more than one
1311init file, one generic in your home directory, and another, specific
1312to the program you are debugging, in the directory where you invoke
1313@value{GDBN}.
1314
c50c785c
JM
1315@item
1316If the command line specified a program to debug, or a process to
1317attach to, or a core file, @value{GDBN} loads any auto-loaded
1318scripts provided for the program or for its loaded shared libraries.
1319@xref{Auto-loading}.
1320
1321If you wish to disable the auto-loading during startup,
1322you must do something like the following:
1323
1324@smallexample
ef5ccd6c 1325$ gdb -iex "set auto-load python-scripts off" myprogram
c50c785c
JM
1326@end smallexample
1327
ef5ccd6c
JM
1328Option @samp{-ex} does not work because the auto-loading is then turned
1329off too late.
c50c785c 1330
5796c8dc 1331@item
ef5ccd6c
JM
1332Executes commands and command files specified by the @samp{-ex} and
1333@samp{-x} options in their specified order. @xref{Command Files}, for
1334more details about @value{GDBN} command files.
5796c8dc
SS
1335
1336@item
1337Reads the command history recorded in the @dfn{history file}.
1338@xref{Command History}, for more details about the command history and the
1339files where @value{GDBN} records it.
1340@end enumerate
1341
1342Init files use the same syntax as @dfn{command files} (@pxref{Command
1343Files}) and are processed by @value{GDBN} in the same way. The init
1344file in your home directory can set options (such as @samp{set
1345complaints}) that affect subsequent processing of command line options
1346and operands. Init files are not executed if you use the @samp{-nx}
1347option (@pxref{Mode Options, ,Choosing Modes}).
1348
1349To display the list of init files loaded by gdb at startup, you
1350can use @kbd{gdb --help}.
1351
1352@cindex init file name
1353@cindex @file{.gdbinit}
1354@cindex @file{gdb.ini}
1355The @value{GDBN} init files are normally called @file{.gdbinit}.
1356The DJGPP port of @value{GDBN} uses the name @file{gdb.ini}, due to
1357the limitations of file names imposed by DOS filesystems. The Windows
ef5ccd6c
JM
1358port 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
1360and suggests to rename the file to the standard name.
5796c8dc
SS
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
1373To 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
1375do not supply @var{expression}, @value{GDBN} will terminate normally;
1376otherwise it will terminate using the result of @var{expression} as the
1377error code.
1378@end table
1379
1380@cindex interrupt
1381An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather
1382terminates the action of any @value{GDBN} command that is in progress and
1383returns to @value{GDBN} command level. It is safe to type the interrupt
1384character at any time because @value{GDBN} does not allow it to take effect
1385until a time when it is safe.
1386
1387If you have been using @value{GDBN} to control an attached process or
1388device, 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
1394If you need to execute occasional shell commands during your
1395debugging session, there is no need to leave or suspend @value{GDBN}; you can
1396just use the @code{shell} command.
1397
1398@table @code
1399@kindex shell
a45ae5f8 1400@kindex !
5796c8dc 1401@cindex shell escape
a45ae5f8
JM
1402@item shell @var{command-string}
1403@itemx !@var{command-string}
1404Invoke a standard shell to execute @var{command-string}.
1405Note that no space is needed between @code{!} and @var{command-string}.
5796c8dc
SS
1406If it exists, the environment variable @code{SHELL} determines which
1407shell 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
1411The utility @code{make} is often needed in development environments.
1412You 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}
1419Execute the @code{make} program with the specified
1420arguments. 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
1428You may want to save the output of @value{GDBN} commands to a file.
1429There are several commands to control @value{GDBN}'s logging.
1430
1431@table @code
1432@kindex set logging
1433@item set logging on
1434Enable logging.
1435@item set logging off
1436Disable logging.
1437@cindex logging file name
1438@item set logging file @var{file}
1439Change the name of the current logfile. The default logfile is @file{gdb.txt}.
1440@item set logging overwrite [on|off]
1441By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if
1442you want @code{set logging on} to overwrite the logfile instead.
1443@item set logging redirect [on|off]
1444By default, @value{GDBN} output will go to both the terminal and the logfile.
1445Set @code{redirect} if you want output to go only to the log file.
1446@kindex show logging
1447@item show logging
1448Show the current values of the logging settings.
1449@end table
1450
1451@node Commands
1452@chapter @value{GDBN} Commands
1453
1454You can abbreviate a @value{GDBN} command to the first few letters of the command
1455name, 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}
1457key to get @value{GDBN} to fill out the rest of a word in a command (or to
1458show 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
1469A @value{GDBN} command is a single line of input. There is no limit on
1470how long it can be. It starts with a command name, which is followed by
1471arguments whose meaning depends on the command name. For example, the
1472command @code{step} accepts an argument which is the number of times to
1473step, as in @samp{step 5}. You can also use the @code{step} command
1474with 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
1478unambiguous. Other possible command abbreviations are listed in the
1479documentation for individual commands. In some cases, even ambiguous
1480abbreviations are allowed; for example, @code{s} is specially defined as
1481equivalent to @code{step} even though there are other commands whose
1482names start with @code{s}. You can test abbreviations by using them as
1483arguments to the @code{help} command.
1484
1485@cindex repeating commands
1486@kindex RET @r{(repeat last command)}
1487A blank line as input to @value{GDBN} (typing just @key{RET}) means to
1488repeat the previous command. Certain commands (for example, @code{run})
1489will not repeat this way; these are commands whose unintentional
1490repetition might cause trouble and which you are unlikely to want to
1491repeat. User-defined commands can disable this feature; see
1492@ref{Define, dont-repeat}.
1493
1494The @code{list} and @code{x} commands, when you repeat them with
1495@key{RET}, construct new arguments rather than repeating
1496exactly 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
1499output, 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
1502repetition after any command that generates this sort of display.
1503
1504@kindex # @r{(a comment)}
1505@cindex comment
1506Any text from a @kbd{#} to the end of the line is a comment; it does
1507nothing. This is useful mainly in command files (@pxref{Command
1508Files,,Command Files}).
1509
1510@cindex repeating command sequences
1511@kindex Ctrl-o @r{(operate-and-get-next)}
1512The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of
1513commands. This command accepts the current line, like @key{RET}, and
1514then fetches the next line relative to the current line from the history
1515for 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
1523only one possibility; it can also show you what the valid possibilities
1524are for the next word in a command, at any time. This works for @value{GDBN}
1525commands, @value{GDBN} subcommands, and the names of symbols in your program.
1526
1527Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest
1528of a word. If there is only one possibility, @value{GDBN} fills in the
1529word, and waits for you to finish the command (or press @key{RET} to
1530enter 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
1542the only @code{info} subcommand beginning with @samp{bre}:
1543
1544@smallexample
1545(@value{GDBP}) info breakpoints
1546@end smallexample
1547
1548@noindent
1549You can either press @key{RET} at this point, to run the @code{info
1550breakpoints} command, or backspace and enter something else, if
1551@samp{breakpoints} does not look like the command you expected. (If you
1552were sure you wanted @code{info breakpoints} in the first place, you
1553might as well just type @key{RET} immediately after @samp{info bre},
1554to exploit command abbreviations rather than command completion).
1555
1556If 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
1558characters and try again, or just press @key{TAB} a second time;
1559@value{GDBN} displays all the possible completions for that word. For
1560example, you might want to set a breakpoint on a subroutine whose name
1561begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN}
1562just sounds the bell. Typing @key{TAB} again displays all the
1563function names in your program that begin with those characters, for
1564example:
1565
1566@smallexample
1567(@value{GDBP}) b make_ @key{TAB}
1568@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see:
1569make_a_section_from_file make_environ
1570make_abs_section make_function_type
1571make_blockvector make_pointer_type
1572make_cleanup make_reference_type
1573make_command make_symbol_completion_list
1574(@value{GDBP}) b make_
1575@end smallexample
1576
1577@noindent
1578After displaying the available possibilities, @value{GDBN} copies your
1579partial input (@samp{b make_} in the example) so you can finish the
1580command.
1581
1582If you just want to see the list of alternatives in the first place, you
1583can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?}
1584means @kbd{@key{META} ?}. You can type this either by holding down a
1585key designated as the @key{META} shift on your keyboard (if there is
1586one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}.
1587
1588@cindex quotes in commands
1589@cindex completion of quoted strings
1590Sometimes the string you need, while logically a ``word'', may contain
1591parentheses or other characters that @value{GDBN} normally excludes from
1592its notion of a word. To permit word completion to work in this
1593situation, you may enclose words in @code{'} (single quote marks) in
1594@value{GDBN} commands.
1595
1596The most likely situation where you might need this is in typing the
1597name of a C@t{++} function. This is because C@t{++} allows function
1598overloading (multiple definitions of the same function, distinguished
1599by argument type). For example, when you want to set a breakpoint you
1600may need to distinguish whether you mean the version of @code{name}
1601that takes an @code{int} parameter, @code{name(int)}, or the version
1602that takes a @code{float} parameter, @code{name(float)}. To use the
1603word-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
1606when you press @key{TAB} or @kbd{M-?} to request word completion:
1607
1608@smallexample
1609(@value{GDBP}) b 'bubble( @kbd{M-?}
1610bubble(double,double) bubble(int,int)
1611(@value{GDBP}) b 'bubble(
1612@end smallexample
1613
1614In some cases, @value{GDBN} can tell that completing a name requires using
1615quotes. When this happens, @value{GDBN} inserts the quote for you (while
1616completing as much as it can) if you do not type the quote in the first
1617place:
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
1626In general, @value{GDBN} can tell that a quote is needed (and inserts it) if
1627you have not yet started typing the argument list when you ask for
1628completion on an overloaded symbol.
1629
1630For more information about overloaded functions, see @ref{C Plus Plus
1631Expressions, ,C@t{++} Expressions}. You can use the command @code{set
1632overload-resolution off} to disable overload resolution;
1633see @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
1639When completing in an expression which looks up a field in a
1640structure, @value{GDBN} also tries@footnote{The completer can be
1641confused by certain kinds of invalid expressions. Also, it only
1642examines the static type of the expression, not the dynamic type.} to
1643limit completions to the field names available in the type of the
1644left-hand-side:
1645
1646@smallexample
1647(@value{GDBP}) p gdb_stdout.@kbd{M-?}
a45ae5f8
JM
1648magic to_fputs to_rewind
1649to_data to_isatty to_write
1650to_delete to_put to_write_async_safe
1651to_flush to_read
5796c8dc
SS
1652@end smallexample
1653
1654@noindent
1655This 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
1657follows:
1658
1659@smallexample
1660struct ui_file
1661@{
1662 int *magic;
1663 ui_file_flush_ftype *to_flush;
1664 ui_file_write_ftype *to_write;
a45ae5f8 1665 ui_file_write_async_safe_ftype *to_write_async_safe;
5796c8dc
SS
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
1682You can always ask @value{GDBN} itself for information on its commands,
1683using the command @code{help}.
1684
1685@table @code
1686@kindex h @r{(@code{help})}
1687@item help
1688@itemx h
1689You can use @code{help} (abbreviated @code{h}) with no arguments to
1690display a short list of named classes of commands:
1691
1692@smallexample
1693(@value{GDBP}) help
1694List of classes of commands:
1695
1696aliases -- Aliases of other commands
1697breakpoints -- Making program stop at certain points
1698data -- Examining data
1699files -- Specifying and examining files
1700internals -- Maintenance commands
1701obscure -- Obscure features
1702running -- Running the program
1703stack -- Examining the stack
1704status -- Status inquiries
1705support -- Support facilities
1706tracepoints -- Tracing of program execution without
1707 stopping the program
1708user-defined -- User-defined commands
1709
1710Type "help" followed by a class name for a list of
1711commands in that class.
1712Type "help" followed by command name for full
1713documentation.
1714Command 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}
1720Using one of the general help classes as an argument, you can get a
1721list of the individual commands in that class. For example, here is the
1722help display for the class @code{status}:
1723
1724@smallexample
1725(@value{GDBP}) help status
1726Status inquiries.
1727
1728List of commands:
1729
1730@c Line break in "show" line falsifies real output, but needed
1731@c to fit in smallbook page size.
1732info -- Generic command for showing things
1733 about the program being debugged
1734show -- Generic command for showing things
1735 about the debugger
1736
1737Type "help" followed by command name for full
1738documentation.
1739Command name abbreviations are allowed if unambiguous.
1740(@value{GDBP})
1741@end smallexample
1742
1743@item help @var{command}
1744With a command name as @code{help} argument, @value{GDBN} displays a
1745short paragraph on how to use that command.
1746
1747@kindex apropos
1748@item apropos @var{args}
1749The @code{apropos} command searches through all of the @value{GDBN}
1750commands, and their documentation, for the regular expression specified in
1751@var{args}. It prints out all matches found. For example:
1752
1753@smallexample
ef5ccd6c 1754apropos alias
5796c8dc
SS
1755@end smallexample
1756
1757@noindent
1758results in:
1759
1760@smallexample
1761@c @group
ef5ccd6c
JM
1762alias -- Define a new command that is an alias of an existing command
1763aliases -- Aliases of other commands
1764d -- Delete some breakpoints or auto-display expressions
1765del -- Delete some breakpoints or auto-display expressions
1766delete -- Delete some breakpoints or auto-display expressions
5796c8dc
SS
1767@c @end group
1768@end smallexample
1769
1770@kindex complete
1771@item complete @var{args}
1772The @code{complete @var{args}} command lists all the possible completions
1773for the beginning of a command. Use @var{args} to specify the beginning of the
1774command you want completed. For example:
1775
1776@smallexample
1777complete i
1778@end smallexample
1779
1780@noindent results in:
1781
1782@smallexample
1783@group
1784if
1785ignore
1786info
1787inspect
1788@end group
1789@end smallexample
1790
1791@noindent This is intended for use by @sc{gnu} Emacs.
1792@end table
1793
1794In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
1795and @code{show} to inquire about the state of your program, or the state
1796of @value{GDBN} itself. Each command supports many topics of inquiry; this
1797manual introduces each of them in the appropriate context. The listings
ef5ccd6c
JM
1798under @code{info} and under @code{show} in the Command, Variable, and
1799Function Index point to all the sub-commands. @xref{Command and Variable
1800Index}.
5796c8dc
SS
1801
1802@c @group
1803@table @code
1804@kindex info
1805@kindex i @r{(@code{info})}
1806@item info
1807This command (abbreviated @code{i}) is for describing the state of your
1808program. For example, you can show the arguments passed to a function
1809with @code{info args}, list the registers currently in use with @code{info
1810registers}, or list the breakpoints you have set with @code{info breakpoints}.
1811You can get a complete list of the @code{info} sub-commands with
1812@w{@code{help info}}.
1813
1814@kindex set
1815@item set
1816You 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
1822In contrast to @code{info}, @code{show} is for describing the state of
1823@value{GDBN} itself.
1824You can change most of the things you can @code{show}, by using the
1825related command @code{set}; for example, you can control what number
1826system is used for displays with @code{set radix}, or simply inquire
1827which is currently in use with @code{show radix}.
1828
1829@kindex info set
1830To display all the settable parameters and their current
1831values, 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
1839Here are three miscellaneous @code{show} subcommands, all of which are
1840exceptional in lacking corresponding @code{set} commands:
1841
1842@table @code
1843@kindex show version
1844@cindex @value{GDBN} version number
1845@item show version
1846Show what version of @value{GDBN} is running. You should include this
1847information in @value{GDBN} bug-reports. If multiple versions of
1848@value{GDBN} are in use at your site, you may need to determine which
1849version of @value{GDBN} you are running; as @value{GDBN} evolves, new
1850commands are introduced, and old ones may wither away. Also, many
1851system vendors ship variant versions of @value{GDBN}, and there are
1852variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well.
1853The 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
1861Display information about permission for copying @value{GDBN}.
1862
1863@kindex show warranty
1864@kindex info warranty
1865@item show warranty
1866@itemx info warranty
1867Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
1868if your version of @value{GDBN} comes with one.
1869
1870@end table
1871
1872@node Running
1873@chapter Running Programs Under @value{GDBN}
1874
1875When you run a program under @value{GDBN}, you must first generate
1876debugging information when you compile it.
1877
1878You may start @value{GDBN} with its arguments, if any, in an environment
1879of your choice. If you are doing native debugging, you may redirect
1880your program's input and output, debug an already running process, or
1881kill 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
cf7f2e2d 1894* Inferiors and Programs:: Debugging multiple inferiors and programs
5796c8dc 1895* Threads:: Debugging programs with multiple threads
cf7f2e2d 1896* Forks:: Debugging forks
5796c8dc
SS
1897* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later
1898@end menu
1899
1900@node Compilation
1901@section Compiling for Debugging
1902
1903In order to debug a program effectively, you need to generate
1904debugging information when you compile it. This debugging information
1905is stored in the object file; it describes the data type of each
1906variable or function and the correspondence between source line numbers
1907and addresses in the executable code.
1908
1909To request debugging information, specify the @samp{-g} option when you run
1910the compiler.
1911
1912Programs that are to be shipped to your customers are compiled with
1913optimizations, using the @samp{-O} compiler option. However, some
1914compilers are unable to handle the @samp{-g} and @samp{-O} options
1915together. Using those compilers, you cannot generate optimized
1916executables containing debugging information.
1917
1918@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or
1919without @samp{-O}, making it possible to debug optimized code. We
1920recommend that you @emph{always} use @samp{-g} whenever you compile a
1921program. You may think your program is correct, but there is no sense
1922in pushing your luck. For more information, see @ref{Optimized Code}.
1923
1924Older versions of the @sc{gnu} C compiler permitted a variant option
1925@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this
1926format; 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
1929expansion (@pxref{Macros}). Most compilers do not include information
1930about preprocessor macros in the debugging information if you specify
a45ae5f8
JM
1931the @option{-g} flag alone. Version 3.1 and later of @value{NGCC},
1932the @sc{gnu} C compiler, provides macro information if you are using
1933the DWARF debugging format, and specify the option @option{-g3}.
1934
1935@xref{Debugging Options,,Options for Debugging Your Program or GCC,
1936gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more
1937information on @value{NGCC} options affecting debug information.
1938
1939You will have the best debugging experience if you use the latest
1940version of the DWARF debugging format that your compiler supports.
1941DWARF is currently the most expressive and best supported debugging
1942format in @value{GDBN}.
5796c8dc
SS
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
1955Use the @code{run} command to start your program under @value{GDBN}.
1956You must first specify the program name (except on VxWorks) with an
1957argument 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
1963If you are running your program in an execution environment that
1964supports processes, @code{run} creates an inferior process and makes
1965that process run your program. In some environments without processes,
1966@code{run} jumps to the start of your program. Other targets,
1967like @samp{remote}, are always running. If you get an error
1968message like this one:
1969
1970@smallexample
1971The "remote" target does not support "run".
1972Try "help target" or "continue".
1973@end smallexample
1974
1975@noindent
1976then use @code{continue} to run your program. You may need @code{load}
1977first (@pxref{load}).
1978
1979The execution of a program is affected by certain information it
1980receives from its superior. @value{GDBN} provides ways to specify this
1981information, which you must do @emph{before} starting your program. (You
1982can change it after starting your program, but such changes only affect
1983your program the next time you start it.) This information may be
1984divided into four categories:
1985
1986@table @asis
1987@item The @emph{arguments.}
1988Specify 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
1990is used to pass the arguments, so that you may use normal conventions
1991(such as wildcard expansion or variable substitution) in describing
1992the arguments.
1993In 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.}
1998Your program normally inherits its environment from @value{GDBN}, but you can
1999use the @value{GDBN} commands @code{set environment} and @code{unset
2000environment} to change parts of the environment that affect
2001your program. @xref{Environment, ,Your Program's Environment}.
2002
2003@item The @emph{working directory.}
2004Your program inherits its working directory from @value{GDBN}. You can set
2005the @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.}
2009Your program normally uses the same device for standard input and
2010standard output as @value{GDBN} is using. You can redirect input and output
2011in the @code{run} command line, or you can use the @code{tty} command to
2012set 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
2017pipes to pass the output of the program you are debugging to another
2018program; if you attempt this, @value{GDBN} is likely to wind up debugging the
2019wrong program.
2020@end table
2021
2022When you issue the @code{run} command, your program begins to execute
2023immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion
2024of how to arrange for your program to stop. Once your program has
2025stopped, you may call functions in your program, using the @code{print}
2026or @code{call} commands. @xref{Data, ,Examining Data}.
2027
2028If the modification time of your symbol file has changed since the last
2029time @value{GDBN} read its symbols, @value{GDBN} discards its symbol
2030table, and reads it again. When it does this, @value{GDBN} tries to retain
2031your current breakpoints.
2032
2033@table @code
2034@kindex start
2035@item start
2036@cindex run to main procedure
2037The name of the main procedure can vary from language to language.
2038With C or C@t{++}, the main procedure name is always @code{main}, but
2039other languages such as Ada do not require a specific name for their
2040main procedure. The debugger provides a convenient way to start the
2041execution of the program and to stop at the beginning of the main
2042procedure, depending on the language used.
2043
2044The @samp{start} command does the equivalent of setting a temporary
2045breakpoint at the beginning of the main procedure and then invoking
2046the @samp{run} command.
2047
2048@cindex elaboration phase
2049Some programs contain an @dfn{elaboration} phase where some startup code is
2050executed before the main procedure is called. This depends on the
2051languages used to write your program. In C@t{++}, for instance,
2052constructors for static and global objects are executed before
2053@code{main} is called. It is therefore possible that the debugger stops
2054before reaching the main procedure. However, the temporary breakpoint
2055will remain to halt execution.
2056
2057Specify the arguments to give to your program as arguments to the
2058@samp{start} command. These arguments will be given verbatim to the
2059underlying @samp{run} command. Note that the same arguments will be
2060reused if no argument is provided during subsequent calls to
2061@samp{start} or @samp{run}.
2062
2063It is sometimes necessary to debug the program during elaboration. In
2064these cases, using the @code{start} command would stop the execution of
2065your program too late, as the program would have already completed the
2066elaboration phase. Under these circumstances, insert breakpoints in your
2067elaboration 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
2073When @samp{exec-wrapper} is set, the specified wrapper is used to
2074launch programs for debugging. @value{GDBN} starts your program
2075with a shell command of the form @kbd{exec @var{wrapper}
2076@var{program}}. Quoting is added to @var{program} and its
2077arguments, but not to @var{wrapper}, so you should add quotes if
2078appropriate for your shell. The wrapper runs until it executes
2079your program, and then @value{GDBN} takes control.
2080
2081You can use any program that eventually calls @code{execve} with
2082its arguments as a wrapper. Several standard Unix utilities do
2083this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending
2084with @code{exec "$@@"} will also work.
2085
2086For example, you can use @code{env} to pass an environment variable to
2087the debugged program, without setting the variable in your shell's
2088environment:
2089
2090@smallexample
2091(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so'
2092(@value{GDBP}) run
2093@end smallexample
2094
2095This 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
2101This option (enabled by default in @value{GDBN}) will turn off the native
2102randomization of the virtual address space of the started program. This option
2103is useful for multiple debugging sessions to make the execution better
2104reproducible and memory addresses reusable across debugging sessions.
2105
a45ae5f8
JM
2106This feature is implemented only on certain targets, including @sc{gnu}/Linux.
2107On @sc{gnu}/Linux you can get the same behavior using
5796c8dc
SS
2108
2109@smallexample
2110(@value{GDBP}) set exec-wrapper setarch `uname -m` -R
2111@end smallexample
2112
2113@item set disable-randomization off
2114Leave the behavior of the started executable unchanged. Some bugs rear their
2115ugly heads only when the program is loaded at certain addresses. If your bug
2116disappears when you run the program under @value{GDBN}, that might be because
2117@value{GDBN} by default disables the address randomization on platforms, such
2118as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set
2119disable-randomization off} to try to reproduce such elusive bugs.
2120
a45ae5f8
JM
2121On targets where it is available, virtual address space randomization
2122protects the programs against certain kinds of security attacks. In these
5796c8dc
SS
2123cases the attacker needs to know the exact location of a concrete executable
2124code. Randomizing its location makes it impossible to inject jumps misusing
2125a code at its expected addresses.
2126
2127Prelinking shared libraries provides a startup performance advantage but it
2128makes addresses in these libraries predictable for privileged processes by
2129having just unprivileged access at the target system. Reading the shared
2130library binary gives enough information for assembling the malicious code
2131misusing it. Still even a prelinked shared library can get loaded at a new
2132random address just requiring the regular relocation process during the
2133startup. Shared libraries not already prelinked are always loaded at
2134a randomly chosen address.
2135
2136Position independent executables (PIE) contain position independent code
2137similar to the shared libraries and therefore such executables get loaded at
2138a randomly chosen address upon startup. PIE executables always load even
2139already prelinked shared libraries at a random address. You can build such
2140executable using @command{gcc -fPIE -pie}.
2141
2142Heap (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
2146Show the current setting of the explicit disable of the native randomization of
2147the 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)
2155The arguments to your program can be specified by the arguments of the
2156@code{run} command.
2157They are passed to a shell, which expands wildcard characters and
2158performs 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
2161the default shell (@file{/bin/sh} on Unix).
2162
2163On non-Unix systems, the program is usually invoked directly by
2164@value{GDBN}, which emulates I/O redirection via the appropriate system
2165calls, and the wildcard characters are expanded by the startup code of
2166the 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
2174Specify 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
2176with no arguments. Once you have run your program with arguments,
2177using @code{set args} before the next @code{run} is the only way to run
2178it again without arguments.
2179
2180@kindex show args
2181@item show args
2182Show 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)
2189The @dfn{environment} consists of a set of environment variables and
2190their values. Environment variables conventionally record such things as
2191your user name, your home directory, your terminal type, and your search
2192path for programs to run. Usually you set up environment variables with
2193the shell and they are inherited by all the other programs you run. When
2194debugging, it can be useful to try running your program with a modified
2195environment without having to start @value{GDBN} over again.
2196
2197@table @code
2198@kindex path
2199@item path @var{directory}
2200Add @var{directory} to the front of the @code{PATH} environment variable
2201(the search path for executables) that will be passed to your program.
2202The value of @code{PATH} used by @value{GDBN} does not change.
2203You may specify several directory names, separated by whitespace or by a
2204system-dependent separator character (@samp{:} on Unix, @samp{;} on
2205MS-DOS and MS-Windows). If @var{directory} is already in the path, it
2206is moved to the front, so it is searched sooner.
2207
2208You can use the string @samp{$cwd} to refer to whatever is the current
2209working directory at the time @value{GDBN} searches the path. If you
2210use @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
2219Display the list of search paths for executables (the @code{PATH}
2220environment variable).
2221
2222@kindex show environment
2223@item show environment @r{[}@var{varname}@r{]}
2224Print the value of environment variable @var{varname} to be given to
2225your program when it starts. If you do not supply @var{varname},
2226print the names and values of all environment variables to be given to
2227your program. You can abbreviate @code{environment} as @code{env}.
2228
2229@kindex set environment
2230@item set environment @var{varname} @r{[}=@var{value}@r{]}
2231Set environment variable @var{varname} to @var{value}. The value
2232changes for your program only, not for @value{GDBN} itself. @var{value} may
2233be any string; the values of environment variables are just strings, and
2234any interpretation is supplied by your program itself. The @var{value}
2235parameter is optional; if it is eliminated, the variable is set to a
2236null value.
2237@c "any string" here does not include leading, trailing
2238@c blanks. Gnu asks: does anyone care?
2239
2240For example, this command:
2241
2242@smallexample
2243set env USER = foo
2244@end smallexample
2245
2246@noindent
2247tells the debugged program, when subsequently run, that its user is named
2248@samp{foo}. (The spaces around @samp{=} are used for clarity here; they
2249are not actually required.)
2250
2251@kindex unset environment
2252@item unset environment @var{varname}
2253Remove variable @var{varname} from the environment to be passed to your
2254program. This is different from @samp{set env @var{varname} =};
2255@code{unset environment} removes the variable from the environment,
2256rather than assigning it an empty value.
2257@end table
2258
2259@emph{Warning:} On Unix systems, @value{GDBN} runs your program using
2260the shell indicated
2261by your @code{SHELL} environment variable if it exists (or
2262@code{/bin/sh} if not). If your @code{SHELL} variable names a shell
2263that 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
2265your program. You may wish to move setting of environment variables to
2266files 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)
2273Each time you start your program with @code{run}, it inherits its
2274working directory from the current working directory of @value{GDBN}.
2275The @value{GDBN} working directory is initially whatever it inherited
2276from its parent process (typically the shell), but you can specify a new
2277working directory in @value{GDBN} with the @code{cd} command.
2278
2279The @value{GDBN} working directory also serves as a default for the commands
2280that specify files for @value{GDBN} to operate on. @xref{Files, ,Commands to
2281Specify Files}.
2282
2283@table @code
2284@kindex cd
2285@cindex change working directory
ef5ccd6c
JM
2286@item cd @r{[}@var{directory}@r{]}
2287Set the @value{GDBN} working directory to @var{directory}. If not
2288given, @var{directory} uses @file{'~'}.
5796c8dc
SS
2289
2290@kindex pwd
2291@item pwd
2292Print the @value{GDBN} working directory.
2293@end table
2294
2295It is generally impossible to find the current working directory of
2296the process being debugged (since a program can change its directory
2297during its run). If you work on a system where @value{GDBN} is
2298configured with the @file{/proc} support, you can use the @code{info
2299proc} command (@pxref{SVR4 Process Information}) to find out the
2300current 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
2308By default, the program you run under @value{GDBN} does input and output to
2309the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal
2310to its own terminal modes to interact with you, but it records the terminal
2311modes your program was using and switches back to them when you continue
2312running your program.
2313
2314@table @code
2315@kindex info terminal
2316@item info terminal
2317Displays information recorded by @value{GDBN} about the terminal modes your
2318program is using.
2319@end table
2320
2321You can redirect your program's input and/or output using shell
2322redirection with the @code{run} command. For example,
2323
2324@smallexample
2325run > outfile
2326@end smallexample
2327
2328@noindent
2329starts your program, diverting its output to the file @file{outfile}.
2330
2331@kindex tty
2332@cindex controlling terminal
2333Another way to specify where your program should do input and output is
2334with the @code{tty} command. This command accepts a file name as
2335argument, and causes this file to be the default for future @code{run}
2336commands. It also resets the controlling terminal for the child
2337process, for future @code{run} commands. For example,
2338
2339@smallexample
2340tty /dev/ttyb
2341@end smallexample
2342
2343@noindent
2344directs that processes started with subsequent @code{run} commands
2345default to do input and output on the terminal @file{/dev/ttyb} and have
2346that as their controlling terminal.
2347
2348An explicit redirection in @code{run} overrides the @code{tty} command's
2349effect on the input/output device, but not its effect on the controlling
2350terminal.
2351
2352When you use the @code{tty} command or redirect input in the @code{run}
2353command, only the input @emph{for your program} is affected. The input
2354for @value{GDBN} still comes from your terminal. @code{tty} is an alias
2355for @code{set inferior-tty}.
2356
2357@cindex inferior tty
2358@cindex set inferior controlling terminal
2359You can use the @code{show inferior-tty} command to tell @value{GDBN} to
2360display the name of the terminal that will be used for future runs of your
2361program.
2362
2363@table @code
2364@item set inferior-tty /dev/ttyb
2365@kindex set inferior-tty
2366Set the tty for the program being debugged to /dev/ttyb.
2367
2368@item show inferior-tty
2369@kindex show inferior-tty
2370Show 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}
2380This command attaches to a running process---one that was started
2381outside @value{GDBN}. (@code{info files} shows your active
2382targets.) The command takes as argument a process ID. The usual way to
2383find out the @var{process-id} of a Unix process is with the @code{ps} utility,
2384or with the @samp{jobs -l} shell command.
2385
2386@code{attach} does not repeat if you press @key{RET} a second time after
2387executing the command.
2388@end table
2389
2390To use @code{attach}, your program must be running in an environment
2391which supports processes; for example, @code{attach} does not work for
2392programs on bare-board targets that lack an operating system. You must
2393also have permission to send the process a signal.
2394
2395When you use @code{attach}, the debugger finds the program running in
2396the process first by looking in the current working directory, then (if
2397the program is not found) by using the source file search path
2398(@pxref{Source Path, ,Specifying Source Directories}). You can also use
2399the @code{file} command to load the program. @xref{Files, ,Commands to
2400Specify Files}.
2401
2402The first thing @value{GDBN} does after arranging to debug the specified
2403process is to stop it. You can examine and modify an attached process
2404with all the @value{GDBN} commands that are ordinarily available when
2405you start processes with @code{run}. You can insert breakpoints; you
2406can step and continue; you can modify storage. If you would rather the
2407process continue running, you may use the @code{continue} command after
2408attaching @value{GDBN} to the process.
2409
2410@table @code
2411@kindex detach
2412@item detach
2413When you have finished debugging the attached process, you can use the
2414@code{detach} command to release it from @value{GDBN} control. Detaching
2415the process continues its execution. After the @code{detach} command,
2416that process and @value{GDBN} become completely independent once more, and you
2417are 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
2419executing the command.
2420@end table
2421
2422If you exit @value{GDBN} while you have an attached process, you detach
2423that process. If you use the @code{run} command, you kill that process.
2424By default, @value{GDBN} asks for confirmation if you try to do either of these
2425things; you can control whether or not you need to confirm by using the
2426@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and
2427Messages}).
2428
2429@node Kill Process
2430@section Killing the Child Process
2431
2432@table @code
2433@kindex kill
2434@item kill
2435Kill the child process in which your program is running under @value{GDBN}.
2436@end table
2437
2438This command is useful if you wish to debug a core dump instead of a
2439running process. @value{GDBN} ignores any core dump file while your program
2440is running.
2441
2442On some operating systems, a program cannot be executed outside @value{GDBN}
2443while 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
2445outside the debugger.
2446
2447The @code{kill} command is also useful if you wish to recompile and
2448relink your program, since on many systems it is impossible to modify an
2449executable file while it is running in a process. In this case, when you
2450next type @code{run}, @value{GDBN} notices that the file has changed, and
2451reads the symbol table again (while trying to preserve your current
2452breakpoint settings).
2453
cf7f2e2d
JM
2454@node Inferiors and Programs
2455@section Debugging Multiple Inferiors and Programs
5796c8dc 2456
cf7f2e2d
JM
2457@value{GDBN} lets you run and debug multiple programs in a single
2458session. In addition, @value{GDBN} on some systems may let you run
2459several programs simultaneously (otherwise you have to exit from one
2460before starting another). In the most general case, you can have
2461multiple threads of execution in each of multiple processes, launched
2462from multiple executables.
5796c8dc
SS
2463
2464@cindex inferior
2465@value{GDBN} represents the state of each program execution with an
2466object called an @dfn{inferior}. An inferior typically corresponds to
2467a process, but is more general and applies also to targets that do not
2468have processes. Inferiors may be created before a process runs, and
cf7f2e2d
JM
2469may be retained after a process exits. Inferiors have unique
2470identifiers that are different from process ids. Usually each
2471inferior will also have its own distinct address space, although some
2472embedded targets may have several inferiors running in different parts
2473of a single address space. Each inferior may in turn have multiple
2474threads running in it.
5796c8dc 2475
cf7f2e2d
JM
2476To find out what inferiors exist at any moment, use @w{@code{info
2477inferiors}}:
5796c8dc
SS
2478
2479@table @code
2480@kindex info inferiors
2481@item info inferiors
2482Print 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
2488the inferior number assigned by @value{GDBN}
2489
2490@item
2491the target system's inferior identifier
cf7f2e2d
JM
2492
2493@item
2494the name of the executable the inferior is running.
2495
5796c8dc
SS
2496@end enumerate
2497
2498@noindent
2499An asterisk @samp{*} preceding the @value{GDBN} inferior number
2500indicates the current inferior.
2501
2502For 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
cf7f2e2d
JM
2508 Num Description Executable
2509 2 process 2307 hello
2510* 1 process 3401 goodbye
5796c8dc
SS
2511@end smallexample
2512
2513To switch focus between inferiors, use the @code{inferior} command:
2514
2515@table @code
2516@kindex inferior @var{infno}
2517@item inferior @var{infno}
2518Make inferior number @var{infno} the current inferior. The argument
2519@var{infno} is the inferior number assigned by @value{GDBN}, as shown
2520in the first field of the @samp{info inferiors} display.
2521@end table
2522
cf7f2e2d
JM
2523
2524You can get multiple executables into a debugging session via the
2525@code{add-inferior} and @w{@code{clone-inferior}} commands. On some
2526systems @value{GDBN} can add inferiors to the debug session
2527automatically by following calls to @code{fork} and @code{exec}. To
2528remove inferiors from the debugging session use the
c50c785c 2529@w{@code{remove-inferiors}} command.
cf7f2e2d
JM
2530
2531@table @code
2532@kindex add-inferior
2533@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ]
2534Adds @var{n} inferiors to be run using @var{executable} as the
2535executable. @var{n} defaults to 1. If no executable is specified,
2536the inferiors begins empty, with no program. You can still assign or
2537change 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} ]
2542Adds @var{n} inferiors ready to execute the same program as inferior
2543@var{infno}. @var{n} defaults to 1. @var{infno} defaults to the
2544number of the current inferior. This is a convenient command when you
2545want 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
2552Added inferior 2.
25531 inferiors added.
2554(@value{GDBP}) info inferiors
2555 Num Description Executable
2556 2 <null> helloworld
2557* 1 process 29964 helloworld
2558@end smallexample
2559
2560You can now simply switch focus to inferior 2 and run it.
2561
c50c785c
JM
2562@kindex remove-inferiors
2563@item remove-inferiors @var{infno}@dots{}
2564Removes the inferior or inferiors @var{infno}@dots{}. It is not
2565possible to remove an inferior that is running with this command. For
2566those, use the @code{kill} or @code{detach} command first.
cf7f2e2d
JM
2567
2568@end table
2569
2570To quit debugging one of the running inferiors that is not the current
2571inferior, you can either detach from it by using the @w{@code{detach
2572inferior}} command (allowing it to run independently), or kill it
c50c785c 2573using the @w{@code{kill inferiors}} command:
5796c8dc
SS
2574
2575@table @code
c50c785c
JM
2576@kindex detach inferiors @var{infno}@dots{}
2577@item detach inferior @var{infno}@dots{}
2578Detach from the inferior or inferiors identified by @value{GDBN}
2579inferior number(s) @var{infno}@dots{}. Note that the inferior's entry
2580still stays on the list of inferiors shown by @code{info inferiors},
2581but its Description will show @samp{<null>}.
5796c8dc 2582
c50c785c
JM
2583@kindex kill inferiors @var{infno}@dots{}
2584@item kill inferiors @var{infno}@dots{}
2585Kill the inferior or inferiors identified by @value{GDBN} inferior
2586number(s) @var{infno}@dots{}. Note that the inferior's entry still
2587stays on the list of inferiors shown by @code{info inferiors}, but its
2588Description will show @samp{<null>}.
5796c8dc
SS
2589@end table
2590
cf7f2e2d 2591After the successful completion of a command such as @code{detach},
c50c785c 2592@code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after
cf7f2e2d
JM
2593a normal process exit, the inferior is still valid and listed with
2594@code{info inferiors}, ready to be restarted.
2595
2596
5796c8dc
SS
2597To be notified when inferiors are started or exit under @value{GDBN}'s
2598control 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
2606The @code{set print inferior-events} command allows you to enable or
2607disable printing of messages when @value{GDBN} notices that new
2608inferiors have started or that inferiors have exited or have been
2609detached. By default, these messages will not be printed.
2610
2611@kindex show print inferior-events
2612@item show print inferior-events
2613Show whether messages will be printed when @value{GDBN} detects that
2614inferiors have started, exited or have been detached.
2615@end table
2616
cf7f2e2d
JM
2617Many commands will work the same with multiple programs as with a
2618single program: e.g., @code{print myglobal} will simply display the
2619value of @code{myglobal} in the current inferior.
2620
2621
2622Occasionaly, when debugging @value{GDBN} itself, it may be useful to
2623get more info about the relationship of inferiors, programs, address
2624spaces in a debug session. You can do that with the @w{@code{maint
2625info program-spaces}} command.
2626
2627@table @code
2628@kindex maint info program-spaces
2629@item maint info program-spaces
2630Print 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
2637the program space number assigned by @value{GDBN}
2638
2639@item
2640the name of the executable loaded into the program space, with e.g.,
2641the @code{file} command.
2642
2643@end enumerate
2644
2645@noindent
2646An asterisk @samp{*} preceding the @value{GDBN} program space number
2647indicates the current program space.
2648
2649In addition, below each program space line, @value{GDBN} prints extra
2650information that isn't suitable to display in tabular form. For
2651example, 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
2661Here we can see that no inferior is running the program @code{hello},
2662while @code{process 21561} is running the program @code{goodbye}. On
2663some targets, it is possible that multiple inferiors are bound to the
2664same program space. The most common example is that of debugging both
2665the 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
2674Here, both inferior 2 and inferior 1 are running in the same program
2675space as a result of inferior 1 having executed a @code{vfork} call.
2676@end table
2677
5796c8dc
SS
2678@node Threads
2679@section Debugging Programs with Multiple Threads
2680
2681@cindex threads of execution
2682@cindex multiple threads
2683@cindex switching threads
2684In some operating systems, such as HP-UX and Solaris, a single program
2685may have more than one @dfn{thread} of execution. The precise semantics
2686of threads differ from one operating system to another, but in general
2687the threads of a single program are akin to multiple processes---except
2688that they share one address space (that is, they can all examine and
2689modify the same variables). On the other hand, each thread has its own
2690registers and execution stack, and perhaps private memory.
2691
2692@value{GDBN} provides these facilities for debugging multi-thread
2693programs:
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}},
2700a 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
2703messages on thread start and exit.
2704@item @samp{set libthread-db-search-path @var{path}}, which lets
2705the user specify which @code{libthread_db} to use if the default choice
2706isn'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.
2712If your @value{GDBN} does not support threads, these commands have no
2713effect. For example, a system without thread support shows no output
2714from @samp{info threads}, and always rejects the @code{thread} command,
2715like this:
2716
2717@smallexample
2718(@value{GDBP}) info threads
2719(@value{GDBP}) thread 1
2720Thread ID 1 not known. Use the "info threads" command to
2721see 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
2729The @value{GDBN} thread debugging facility allows you to observe all
2730threads while your program runs---but whenever @value{GDBN} takes
2731control, one thread in particular is always the focus of debugging.
2732This thread is called the @dfn{current thread}. Debugging commands show
2733program 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'.
2740Whenever @value{GDBN} detects a new thread in your program, it displays
2741the target system's identification for the thread with a message in the
2742form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
2743whose form varies depending on the particular system. For example, on
2744@sc{gnu}/Linux, you might see
2745
2746@smallexample
c50c785c 2747[New Thread 0x41e02940 (LWP 25582)]
5796c8dc
SS
2748@end smallexample
2749
2750@noindent
2751when @value{GDBN} notices a new thread. In contrast, on an SGI system,
2752the @var{systag} is simply something like @samp{process 368}, with no
2753further 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)
2765For debugging purposes, @value{GDBN} associates its own thread
2766number---always a single integer---with each thread in your program.
2767
2768@table @code
2769@kindex info threads
c50c785c
JM
2770@item info threads @r{[}@var{id}@dots{}@r{]}
2771Display a summary of all threads currently in your program. Optional
2772argument @var{id}@dots{} is one or more thread ids separated by spaces, and
2773means to print information only about the specified thread or threads.
2774@value{GDBN} displays for each thread (in this order):
5796c8dc
SS
2775
2776@enumerate
2777@item
2778the thread number assigned by @value{GDBN}
2779
2780@item
2781the target system's thread identifier (@var{systag})
2782
c50c785c
JM
2783@item
2784the thread's name, if one is known. A thread can either be named by
2785the user (see @code{thread name}, below), or, in some cases, by the
2786program itself.
2787
5796c8dc
SS
2788@item
2789the current stack frame summary for that thread
2790@end enumerate
2791
2792@noindent
2793An asterisk @samp{*} to the left of the @value{GDBN} thread number
2794indicates the current thread.
2795
2796For 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
c50c785c
JM
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)
5796c8dc
SS
2806 at threadtest.c:68
2807@end smallexample
2808
5796c8dc
SS
2809On Solaris, you can display more information about user threads with a
2810Solaris-specific command:
2811
2812@table @code
2813@item maint info sol-threads
2814@kindex maint info sol-threads
2815@cindex thread info (Solaris)
2816Display info on Solaris user threads.
2817@end table
2818
2819@table @code
2820@kindex thread @var{threadno}
2821@item thread @var{threadno}
2822Make thread number @var{threadno} the current thread. The command
2823argument @var{threadno} is the internal @value{GDBN} thread number, as
2824shown in the first field of the @samp{info threads} display.
2825@value{GDBN} responds by displaying the system identifier of the thread
2826you selected, and its current stack frame summary:
2827
2828@smallexample
5796c8dc 2829(@value{GDBP}) thread 2
c50c785c
JM
2830[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))]
2831#0 some_function (ignore=0x0) at example.c:8
28328 printf ("hello\n");
5796c8dc
SS
2833@end smallexample
2834
2835@noindent
2836As with the @samp{[New @dots{}]} message, the form of the text after
2837@samp{Switching to} depends on your system's conventions for identifying
2838threads.
2839
cf7f2e2d
JM
2840@vindex $_thread@r{, convenience variable}
2841The debugger convenience variable @samp{$_thread} contains the number
2842of the current thread. You may find this useful in writing breakpoint
2843conditional expressions, command scripts, and so forth. See
2844@xref{Convenience Vars,, Convenience Variables}, for general
2845information on convenience variables.
2846
5796c8dc
SS
2847@kindex thread apply
2848@cindex apply command to several threads
c50c785c 2849@item thread apply [@var{threadno} | all] @var{command}
5796c8dc
SS
2850The @code{thread apply} command allows you to apply the named
2851@var{command} to one or more threads. Specify the numbers of the
2852threads that you want affected with the command argument
2853@var{threadno}. It can be a single thread number, one of the numbers
2854shown in the first field of the @samp{info threads} display; or it
2855could be a range of thread numbers, as in @code{2-4}. To apply a
2856command to all threads, type @kbd{thread apply all @var{command}}.
2857
c50c785c
JM
2858@kindex thread name
2859@cindex name a thread
2860@item thread name [@var{name}]
2861This command assigns a name to the current thread. If no argument is
2862given, any existing user-specified name is removed. The thread name
2863appears in the @samp{info threads} display.
2864
2865On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to
2866determine the name of the thread as given by the OS. On these
2867systems, a name specified with @samp{thread name} will override the
2868system-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}]
2874Search for and display thread ids whose name or @var{systag}
2875matches the supplied regular expression.
2876
2877As well as being the complement to the @samp{thread name} command,
2878this command also allows you to identify a thread by its target
2879@var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag}
2880is the LWP id.
2881
2882@smallexample
2883(@value{GDBN}) thread find 26688
2884Thread 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
5796c8dc
SS
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
2895The @code{set print thread-events} command allows you to enable or
2896disable printing of messages when @value{GDBN} notices that new threads have
2897started or that threads have exited. By default, these messages will
2898be printed if detection of these events is supported by the target.
2899Note that these messages cannot be disabled on all targets.
2900
2901@kindex show print thread-events
2902@item show print thread-events
2903Show whether messages will be printed when @value{GDBN} detects that threads
2904have started and exited.
2905@end table
2906
2907@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for
2908more information about how @value{GDBN} behaves when you stop and start
2909programs with multiple threads.
2910
2911@xref{Set Watchpoints,,Setting Watchpoints}, for information about
2912watchpoints in programs with multiple threads.
2913
ef5ccd6c 2914@anchor{set libthread-db-search-path}
5796c8dc
SS
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{]}
2919If this variable is set, @var{path} is a colon-separated list of
2920directories @value{GDBN} will use to search for @code{libthread_db}.
2921If you omit @var{path}, @samp{libthread-db-search-path} will be reset to
a45ae5f8
JM
2922its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems).
2923Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH}
2924macro.
5796c8dc
SS
2925
2926On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper''
2927@code{libthread_db} library to obtain information about threads in the
2928inferior process. @value{GDBN} will use @samp{libthread-db-search-path}
ef5ccd6c
JM
2929to find @code{libthread_db}. @value{GDBN} also consults first if inferior
2930specific thread debugging library loading is enabled
2931by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}).
a45ae5f8
JM
2932
2933A special entry @samp{$sdir} for @samp{libthread-db-search-path}
2934refers to the default system directories that are
ef5ccd6c
JM
2935normally searched for loading shared libraries. The @samp{$sdir} entry
2936is the only kind not needing to be enabled by @samp{set auto-load libthread-db}
2937(@pxref{libthread_db.so.1 file}).
a45ae5f8
JM
2938
2939A special entry @samp{$pdir} for @samp{libthread-db-search-path}
2940refers to the directory from which @code{libpthread}
2941was loaded in the inferior process.
5796c8dc
SS
2942
2943For any @code{libthread_db} library @value{GDBN} finds in above directories,
2944@value{GDBN} attempts to initialize it with the current inferior process.
2945If this initialization fails (which could happen because of a version
2946mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN}
2947will unload @code{libthread_db}, and continue with the next directory.
2948If none of @code{libthread_db} libraries initialize successfully,
2949@value{GDBN} will issue a warning and thread debugging will be disabled.
2950
2951Setting @code{libthread-db-search-path} is currently implemented
2952only on some platforms.
2953
2954@kindex show libthread-db-search-path
2955@item show libthread-db-search-path
2956Display current libthread_db search path.
c50c785c
JM
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
2963Turns on or off display of @code{libthread_db}-related events.
2964Use @code{1} to enable, @code{0} to disable.
5796c8dc
SS
2965@end table
2966
cf7f2e2d
JM
2967@node Forks
2968@section Debugging Forks
5796c8dc
SS
2969
2970@cindex fork, debugging programs which call
2971@cindex multiple processes
2972@cindex processes, multiple
2973On most systems, @value{GDBN} has no special support for debugging
2974programs which create additional processes using the @code{fork}
2975function. When a program forks, @value{GDBN} will continue to debug the
2976parent process and the child process will run unimpeded. If you have
2977set a breakpoint in any code which the child then executes, the child
2978will get a @code{SIGTRAP} signal which (unless it catches the signal)
2979will cause it to terminate.
2980
2981However, if you want to debug the child process there is a workaround
2982which isn't too painful. Put a call to @code{sleep} in the code which
2983the child process executes after the fork. It may be useful to sleep
2984only if a certain environment variable is set, or a certain file exists,
2985so that the delay need not occur when you don't want to run @value{GDBN}
2986on the child. While the child is sleeping, use the @code{ps} program to
2987get 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
2989the child process (@pxref{Attach}). From that point on you can debug
2990the child process just like any other process which you attached to.
2991
2992On some systems, @value{GDBN} provides support for debugging programs that
2993create additional processes using the @code{fork} or @code{vfork} functions.
2994Currently, the only platforms with this feature are HP-UX (11.x and later
2995only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
2996
2997By default, when a program forks, @value{GDBN} will continue to debug
2998the parent process and the child process will run unimpeded.
2999
3000If you want to follow the child process instead of the parent process,
3001use 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}
3006Set 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
3008process. The @var{mode} argument can be:
3009
3010@table @code
3011@item parent
3012The original process is debugged after a fork. The child process runs
3013unimpeded. This is the default.
3014
3015@item child
3016The new process is debugged after a fork. The parent process runs
3017unimpeded.
3018
3019@end table
3020
3021@kindex show follow-fork-mode
3022@item show follow-fork-mode
3023Display the current debugger response to a @code{fork} or @code{vfork} call.
3024@end table
3025
3026@cindex debugging multiple processes
3027On Linux, if you want to debug both the parent and child processes, use the
3028command @w{@code{set detach-on-fork}}.
3029
3030@table @code
3031@kindex set detach-on-fork
3032@item set detach-on-fork @var{mode}
3033Tells gdb whether to detach one of the processes after a fork, or
3034retain debugger control over them both.
3035
3036@table @code
3037@item on
3038The child process (or parent process, depending on the value of
3039@code{follow-fork-mode}) will be detached and allowed to run
3040independently. This is the default.
3041
3042@item off
3043Both processes will be held under the control of @value{GDBN}.
3044One process (child or parent, depending on the value of
3045@code{follow-fork-mode}) is debugged as usual, while the other
3046is held suspended.
3047
3048@end table
3049
3050@kindex show detach-on-fork
3051@item show detach-on-fork
3052Show whether detach-on-fork mode is on/off.
3053@end table
3054
3055If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN}
3056will retain control of all forked processes (including nested forks).
3057You can list the forked processes under the control of @value{GDBN} by
3058using the @w{@code{info inferiors}} command, and switch from one fork
cf7f2e2d
JM
3059to another by using the @code{inferior} command (@pxref{Inferiors and
3060Programs, ,Debugging Multiple Inferiors and Programs}).
5796c8dc
SS
3061
3062To quit debugging one of the forked processes, you can either detach
c50c785c
JM
3063from it by using the @w{@code{detach inferiors}} command (allowing it
3064to run independently), or kill it using the @w{@code{kill inferiors}}
cf7f2e2d
JM
3065command. @xref{Inferiors and Programs, ,Debugging Multiple Inferiors
3066and Programs}.
5796c8dc
SS
3067
3068If 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
3070breakpoint 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
3072the child process's @code{main}.
3073
3074On some systems, when a child process is spawned by @code{vfork}, you
3075cannot debug the child or parent until an @code{exec} call completes.
3076
3077If you issue a @code{run} command to @value{GDBN} after an @code{exec}
cf7f2e2d
JM
3078call executes, the new target restarts. To restart the parent
3079process, use the @code{file} command with the parent executable name
3080as its argument. By default, after an @code{exec} call executes,
3081@value{GDBN} discards the symbols of the previous executable image.
3082You can change this behaviour with the @w{@code{set follow-exec-mode}}
3083command.
3084
3085@table @code
3086@kindex set follow-exec-mode
3087@item set follow-exec-mode @var{mode}
3088
3089Set 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
3097new inferior. The program the process was running before the
3098@code{exec} call can be restarted afterwards by restarting the
3099original inferior.
3100
3101For 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
3109process 12020 is executing new program: prog2
3110Program 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
3119executable image replaces the previous executable loaded in the
3120inferior. Restarting the inferior after the @code{exec} call, with
3121e.g., the @code{run} command, restarts the executable the process was
3122running after the @code{exec} call. This is the default mode.
3123
3124For example:
3125
3126@smallexample
3127(@value{GDBP}) info inferiors
3128 Id Description Executable
3129* 1 <null> prog1
3130(@value{GDBP}) run
3131process 12020 is executing new program: prog2
3132Program 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
5796c8dc
SS
3140
3141You can use the @code{catch} command to make @value{GDBN} stop whenever
3142a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set
3143Catchpoints, ,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
3154On certain operating systems@footnote{Currently, only
3155@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a
3156program's state, called a @dfn{checkpoint}, and come back to it
3157later.
3158
3159Returning to a checkpoint effectively undoes everything that has
3160happened in the program since the @code{checkpoint} was saved. This
3161includes changes in memory, registers, and even (within some limits)
3162system state. Effectively, it is like going back in time to the
3163moment when the checkpoint was saved.
3164
3165Thus, if you're stepping thru a program and you think you're
3166getting close to the point where things go wrong, you can save
3167a checkpoint. Then, if you accidentally go too far and miss
3168the critical statement, instead of having to restart your program
3169from the beginning, you can just go back to the checkpoint and
3170start again from there.
3171
3172This can be especially useful if it takes a lot of time or
3173steps to reach the point where you think the bug occurs.
3174
3175To use the @code{checkpoint}/@code{restart} method of debugging:
3176
3177@table @code
3178@kindex checkpoint
3179@item checkpoint
3180Save a snapshot of the debugged program's current execution state.
3181The @code{checkpoint} command takes no arguments, but each checkpoint
3182is assigned a small integer id, similar to a breakpoint id.
3183
3184@kindex info checkpoints
3185@item info checkpoints
3186List the checkpoints that have been saved in the current debugging
3187session. For each checkpoint, the following information will be
3188listed:
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}
3199Restore the program state that was saved as checkpoint number
3200@var{checkpoint-id}. All program variables, registers, stack frames
3201etc.@: will be returned to the values that they had when the checkpoint
3202was saved. In essence, gdb will ``wind back the clock'' to the point
3203in time when the checkpoint was saved.
3204
3205Note that breakpoints, @value{GDBN} variables, command history etc.
3206are not affected by restoring a checkpoint. In general, a checkpoint
3207only restores things that reside in the program being debugged, not in
3208the debugger.
3209
3210@kindex delete checkpoint @var{checkpoint-id}
3211@item delete checkpoint @var{checkpoint-id}
3212Delete the previously-saved checkpoint identified by @var{checkpoint-id}.
3213
3214@end table
3215
3216Returning to a previously saved checkpoint will restore the user state
3217of the program being debugged, plus a significant subset of the system
3218(OS) state, including file pointers. It won't ``un-write'' data from
3219a file, but it will rewind the file pointer to the previous location,
3220so that the previously written data can be overwritten. For files
3221opened in read mode, the pointer will also be restored so that the
3222previously read data can be read again.
3223
3224Of course, characters that have been sent to a printer (or other
3225external device) cannot be ``snatched back'', and characters received
3226from eg.@: a serial device can be removed from internal program buffers,
3227but they cannot be ``pushed back'' into the serial pipeline, ready to
3228be received again. Similarly, the actual contents of files that have
3229been changed cannot be restored (at this time).
3230
3231However, within those constraints, you actually can ``rewind'' your
3232program to a previously saved point in time, and begin debugging it
3233again --- and you can change the course of events so as to debug a
3234different execution path this time.
3235
3236@cindex checkpoints and process id
3237Finally, there is one bit of internal program state that will be
3238different when you return to a checkpoint --- the program's process
3239id. Each checkpoint will have a unique process id (or @var{pid}),
3240and each will be different from the program's original @var{pid}.
3241If your program has saved a local copy of its process id, this could
3242potentially pose a problem.
3243
3244@subsection A Non-obvious Benefit of Using Checkpoints
3245
3246On some systems such as @sc{gnu}/Linux, address space randomization
3247is performed on new processes for security reasons. This makes it
3248difficult or impossible to set a breakpoint, or watchpoint, on an
3249absolute address if you have to restart the program, since the
3250absolute location of a symbol will change from one execution to the
3251next.
3252
3253A checkpoint, however, is an @emph{identical} copy of a process.
3254Therefore if you create a checkpoint at (eg.@:) the start of main,
3255and simply return to that checkpoint instead of restarting the
3256process, you can avoid the effects of address randomization and
3257your symbols will all stay in the same place.
3258
3259@node Stopping
3260@chapter Stopping and Continuing
3261
3262The principal purposes of using a debugger are so that you can stop your
3263program before it terminates; or so that, if your program runs into
3264trouble, you can investigate and find out why.
3265
3266Inside @value{GDBN}, your program may stop for any of several reasons,
3267such 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
3269change variables, set new breakpoints or remove old ones, and then
3270continue execution. Usually, the messages shown by @value{GDBN} provide
3271ample explanation of the status of your program---but you can also
3272explicitly request this information at any time.
3273
3274@table @code
3275@kindex info program
3276@item info program
3277Display information about the status of your program: whether it is
3278running 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
a45ae5f8
JM
3284* Skipping Over Functions and Files::
3285 Skipping over functions and files
5796c8dc
SS
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
3294A @dfn{breakpoint} makes your program stop whenever a certain point in
3295the program is reached. For each breakpoint, you can add conditions to
3296control in finer detail whether your program stops. You can set
3297breakpoints with the @code{break} command and its variants (@pxref{Set
3298Breaks, ,Setting Breakpoints}), to specify the place where your program
3299should stop by line number, function name or exact address in the
3300program.
3301
3302On some systems, you can set breakpoints in shared libraries before
3303the executable is run. There is a minor limitation on HP-UX systems:
3304you must wait until the executable is run in order to set breakpoints
3305in shared library routines that are not called directly by the program
3306(for example, routines that are arguments in a @code{pthread_create}
3307call).
3308
3309@cindex watchpoints
3310@cindex data breakpoints
3311@cindex memory tracing
3312@cindex breakpoint on memory address
3313@cindex breakpoint on variable modification
3314A @dfn{watchpoint} is a special breakpoint that stops your program
3315when the value of an expression changes. The expression may be a value
3316of a variable, or it could involve values of one or more variables
3317combined by operators, such as @samp{a + b}. This is sometimes called
3318@dfn{data breakpoints}. You must use a different command to set
3319watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside
3320from that, you can manage a watchpoint like any other breakpoint: you
3321enable, disable, and delete both breakpoints and watchpoints using the
3322same commands.
3323
3324You can arrange to have values from your program displayed automatically
3325whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,,
3326Automatic Display}.
3327
3328@cindex catchpoints
3329@cindex breakpoint on events
3330A @dfn{catchpoint} is another special breakpoint that stops your program
3331when a certain kind of event occurs, such as the throwing of a C@t{++}
3332exception or the loading of a library. As with watchpoints, you use a
3333different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting
3334Catchpoints}), but aside from that, you can manage a catchpoint like any
3335other 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
3341catchpoint when you create it; these numbers are successive integers
3342starting with one. In many of the commands for controlling various
3343features of breakpoints you use the breakpoint number to say which
3344breakpoint 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
3346enable it again.
3347
3348@cindex breakpoint ranges
3349@cindex ranges of breakpoints
3350Some @value{GDBN} commands accept a range of breakpoints on which to
3351operate. A breakpoint range is either a single breakpoint number, like
3352@samp{5}, or two such numbers, in increasing order, separated by a
3353hyphen, like @samp{5-7}. When a breakpoint range is given to a command,
3354all 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
ef5ccd6c 3364* Dynamic Printf:: Dynamic printf
cf7f2e2d 3365* Save Breakpoints:: How to save breakpoints in a file
ef5ccd6c 3366* Static Probe Points:: Listing static probe points
5796c8dc
SS
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
3383Breakpoints are set with the @code{break} command (abbreviated
3384@code{b}). The debugger convenience variable @samp{$bpnum} records the
3385number of the breakpoint you've set most recently; see @ref{Convenience
3386Vars,, Convenience Variables}, for a discussion of what you can do with
3387convenience variables.
3388
3389@table @code
3390@item break @var{location}
3391Set a breakpoint at the given @var{location}, which can specify a
3392function name, a line number, or an address of an instruction.
3393(@xref{Specify Location}, for a list of all the possible ways to
3394specify a @var{location}.) The breakpoint will stop your program just
3395before it executes any of the code in the specified @var{location}.
3396
3397When using source languages that permit overloading of symbols, such as
3398C@t{++}, a function name may refer to more than one possible place to break.
3399@xref{Ambiguous Expressions,,Ambiguous Expressions}, for a discussion of
3400that situation.
3401
3402It is also possible to insert a breakpoint that will stop the program
3403only if a specific thread (@pxref{Thread-Specific Breakpoints})
3404or a specific task (@pxref{Ada Tasks}) hits that breakpoint.
3405
3406@item break
3407When called without any arguments, @code{break} sets a breakpoint at
3408the next instruction to be executed in the selected stack frame
3409(@pxref{Stack, ,Examining the Stack}). In any selected frame but the
3410innermost, this makes your program stop as soon as control
3411returns to that frame. This is similar to the effect of a
3412@code{finish} command in the frame inside the selected frame---except
3413that @code{finish} does not leave an active breakpoint. If you use
3414@code{break} without an argument in the innermost frame, @value{GDBN} stops
3415the next time it reaches the current location; this may be useful
3416inside loops.
3417
3418@value{GDBN} normally ignores breakpoints when it resumes execution, until at
3419least one instruction has been executed. If it did not do this, you
3420would be unable to proceed past a breakpoint without first disabling the
3421breakpoint. This rule applies whether or not the breakpoint already
3422existed when your program stopped.
3423
3424@item break @dots{} if @var{cond}
3425Set a breakpoint with condition @var{cond}; evaluate the expression
3426@var{cond} each time the breakpoint is reached, and stop only if the
3427value is nonzero---that is, if @var{cond} evaluates as true.
3428@samp{@dots{}} stands for one of the possible arguments described
3429above (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}
3434Set a breakpoint enabled only for one stop. @var{args} are the
3435same as for the @code{break} command, and the breakpoint is set in the same
3436way, but the breakpoint is automatically deleted after the first time your
3437program stops there. @xref{Disabling, ,Disabling Breakpoints}.
3438
3439@kindex hbreak
3440@cindex hardware breakpoints
3441@item hbreak @var{args}
3442Set 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
3444breakpoint requires hardware support and some target hardware may not
3445have this support. The main purpose of this is EPROM/ROM code
3446debugging, so you can set a breakpoint at an instruction without
3447changing the instruction. This can be used with the new trap-generation
3448provided by SPARClite DSU and most x86-based targets. These targets
3449will generate traps when a program accesses some data or instruction
3450address that is assigned to the debug registers. However the hardware
3451breakpoint registers can take a limited number of breakpoints. For
3452example, 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
3454or disable unused hardware breakpoints before setting new ones
3455(@pxref{Disabling, ,Disabling Breakpoints}).
3456@xref{Conditions, ,Break Conditions}.
3457For remote targets, you can restrict the number of hardware
3458breakpoints @value{GDBN} will use, see @ref{set remote
3459hardware-breakpoint-limit}.
3460
3461@kindex thbreak
3462@item thbreak @var{args}
3463Set a hardware-assisted breakpoint enabled only for one stop. @var{args}
3464are the same as for the @code{hbreak} command and the breakpoint is set in
3465the same way. However, like the @code{tbreak} command,
3466the breakpoint is automatically deleted after the
3467first time your program stops there. Also, like the @code{hbreak}
3468command, the breakpoint requires hardware support and some target hardware
3469may not have this support. @xref{Disabling, ,Disabling Breakpoints}.
3470See also @ref{Conditions, ,Break Conditions}.
3471
3472@kindex rbreak
3473@cindex regular expression
cf7f2e2d 3474@cindex breakpoints at functions matching a regexp
5796c8dc
SS
3475@cindex set breakpoints in many functions
3476@item rbreak @var{regex}
3477Set breakpoints on all functions matching the regular expression
3478@var{regex}. This command sets an unconditional breakpoint on all
3479matches, printing a list of all breakpoints it set. Once these
3480breakpoints are set, they are treated just like the breakpoints set with
3481the @code{break} command. You can delete them, disable them, or make
3482them conditional the same way as any other breakpoint.
3483
3484The syntax of the regular expression is the standard one used with tools
3485like @file{grep}. Note that this is different from the syntax used by
3486shells, so for instance @code{foo*} matches all functions that include
3487an @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
3489match only functions that begin with @code{foo}, use @code{^foo}.
3490
3491@cindex non-member C@t{++} functions, set breakpoint in
3492When debugging C@t{++} programs, @code{rbreak} is useful for setting
3493breakpoints on overloaded functions that are not members of any special
3494classes.
3495
3496@cindex set breakpoints on all functions
3497The @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
cf7f2e2d
JM
3504@item rbreak @var{file}:@var{regex}
3505If @code{rbreak} is called with a filename qualification, it limits
3506the search for functions matching the given regular expression to the
3507specified @var{file}. This can be used, for example, to set breakpoints on
3508every function in a given file:
3509
3510@smallexample
3511(@value{GDBP}) rbreak file.c:.
3512@end smallexample
3513
3514The colon separating the filename qualifier from the regex may
3515optionally be surrounded by spaces.
3516
5796c8dc
SS
3517@kindex info breakpoints
3518@cindex @code{$_} and @code{info breakpoints}
c50c785c
JM
3519@item info breakpoints @r{[}@var{n}@dots{}@r{]}
3520@itemx info break @r{[}@var{n}@dots{}@r{]}
5796c8dc
SS
3521Print a table of all breakpoints, watchpoints, and catchpoints set and
3522not deleted. Optional argument @var{n} means print information only
c50c785c
JM
3523about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
3524For each breakpoint, following columns are printed:
5796c8dc
SS
3525
3526@table @emph
3527@item Breakpoint Numbers
3528@item Type
3529Breakpoint, watchpoint, or catchpoint.
3530@item Disposition
3531Whether the breakpoint is marked to be disabled or deleted when hit.
3532@item Enabled or Disabled
3533Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
3534that are not enabled.
3535@item Address
3536Where the breakpoint is in your program, as a memory address. For a
3537pending breakpoint whose address is not yet known, this field will
3538contain @samp{<PENDING>}. Such breakpoint won't fire until a shared
3539library that has the symbol or line referred by breakpoint is loaded.
3540See below for details. A breakpoint with several locations will
3541have @samp{<MULTIPLE>} in this field---see below for details.
3542@item What
3543Where the breakpoint is in the source for your program, as a file and
3544line number. For a pending breakpoint, the original string passed to
3545the breakpoint command will be listed as it cannot be resolved until
3546the appropriate shared library is loaded in the future.
3547@end table
3548
3549@noindent
ef5ccd6c
JM
3550If 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
3553is evaluated by the target. The @code{info break} command shows
3554the condition on the line following the affected breakpoint, together with
3555its condition evaluation mode in between parentheses.
3556
3557Breakpoint commands, if any, are listed after that. A pending breakpoint is
3558allowed to have a condition specified for it. The condition is not parsed for
3559validity until a shared library is loaded that allows the pending
3560breakpoint to resolve to a valid location.
5796c8dc
SS
3561
3562@noindent
3563@code{info break} with a breakpoint
3564number @var{n} as argument lists only that breakpoint. The
3565convenience variable @code{$_} and the default examining-address for
3566the @code{x} command are set to the address of the last breakpoint
3567listed (@pxref{Memory, ,Examining Memory}).
3568
3569@noindent
3570@code{info break} displays a count of the number of times the breakpoint
3571has been hit. This is especially useful in conjunction with the
3572@code{ignore} command. You can ignore a large number of breakpoint
3573hits, look at the breakpoint info to see how many times the breakpoint
3574was hit, and then run again, ignoring one less than that number. This
3575will get you quickly to the last hit of that breakpoint.
ef5ccd6c
JM
3576
3577@noindent
3578For a breakpoints with an enable count (xref) greater than 1,
3579@code{info break} also displays that count.
3580
5796c8dc
SS
3581@end table
3582
3583@value{GDBN} allows you to set any number of breakpoints at the same place in
3584your program. There is nothing silly or meaningless about this. When
3585the breakpoints are conditional, this is even useful
3586(@pxref{Conditions, ,Break Conditions}).
3587
3588@cindex multiple locations, breakpoints
3589@cindex breakpoints, multiple locations
3590It is possible that a breakpoint corresponds to several locations
3591in your program. Examples of this situation are:
3592
3593@itemize @bullet
a45ae5f8
JM
3594@item
3595Multiple functions in the program may have the same name.
3596
5796c8dc
SS
3597@item
3598For a C@t{++} constructor, the @value{NGCC} compiler generates several
3599instances of the function body, used in different cases.
3600
3601@item
3602For a C@t{++} template function, a given line in the function can
3603correspond to any number of instantiations.
3604
3605@item
3606For an inlined function, a given source line can correspond to
3607several places where that function is inlined.
3608@end itemize
3609
3610In all those cases, @value{GDBN} will insert a breakpoint at all
a45ae5f8 3611the relevant locations.
5796c8dc
SS
3612
3613A breakpoint with multiple locations is displayed in the breakpoint
3614table using several rows---one header row, followed by one row for
3615each breakpoint location. The header row has @samp{<MULTIPLE>} in the
3616address column. The rows for individual locations contain the actual
3617addresses for locations, and show the functions to which those
3618locations belong. The number column for a location is of the form
3619@var{breakpoint-number}.@var{location-number}.
3620
3621For example:
3622
3623@smallexample
3624Num Type Disp Enb Address What
36251 breakpoint keep y <MULTIPLE>
3626 stop only if i==1
3627 breakpoint already hit 1 time
36281.1 y 0x080486a2 in void foo<int>() at t.cc:8
36291.2 y 0x080486ca in void foo<double>() at t.cc:8
3630@end smallexample
3631
3632Each 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
3635delete the individual locations from the list, you can only delete the
3636entire list of locations that belong to their parent breakpoint (with
3637the @kbd{delete @var{num}} command, where @var{num} is the number of
3638the parent breakpoint, 1 in the above example). Disabling or enabling
3639the parent breakpoint (@pxref{Disabling}) affects all of the locations
3640that belong to that breakpoint.
3641
3642@cindex pending breakpoints
3643It's quite common to have a breakpoint inside a shared library.
3644Shared libraries can be loaded and unloaded explicitly,
3645and possibly repeatedly, as the program is executed. To support
3646this use case, @value{GDBN} updates breakpoint locations whenever
3647any shared library is loaded or unloaded. Typically, you would
3648set a breakpoint in a shared library at the beginning of your
3649debugging session, when the library is not loaded, and when the
3650symbols from the library are not available. When you try to set
3651breakpoint, @value{GDBN} will ask you if you want to set
3652a so called @dfn{pending breakpoint}---breakpoint whose address
3653is not yet resolved.
3654
3655After the program is run, whenever a new shared library is loaded,
3656@value{GDBN} reevaluates all the breakpoints. When a newly loaded
3657shared library contains the symbol or line referred to by some
3658pending breakpoint, that breakpoint is resolved and becomes an
3659ordinary breakpoint. When a library is unloaded, all breakpoints
3660that refer to its symbols or source lines become pending again.
3661
3662This logic works for breakpoints with multiple locations, too. For
3663example, if you have a breakpoint in a C@t{++} template function, and
3664a newly loaded shared library has an instantiation of that template,
3665a new location is added to the list of locations for the breakpoint.
3666
3667Except for having unresolved address, pending breakpoints do not
3668differ from regular breakpoints. You can set conditions or commands,
3669enable and disable them and perform other breakpoint operations.
3670
3671@value{GDBN} provides some additional commands for controlling what
3672happens when the @samp{break} command cannot resolve breakpoint
3673address specification to an address:
3674
3675@kindex set breakpoint pending
3676@kindex show breakpoint pending
3677@table @code
3678@item set breakpoint pending auto
3679This is the default behavior. When @value{GDBN} cannot find the breakpoint
3680location, it queries you whether a pending breakpoint should be created.
3681
3682@item set breakpoint pending on
3683This indicates that an unrecognized breakpoint location should automatically
3684result in a pending breakpoint being created.
3685
3686@item set breakpoint pending off
3687This indicates that pending breakpoints are not to be created. Any
3688unrecognized breakpoint location results in an error. This setting does
3689not affect any pending breakpoints previously created.
3690
3691@item show breakpoint pending
3692Show the current behavior setting for creating pending breakpoints.
3693@end table
3694
3695The settings above only affect the @code{break} command and its
3696variants. Once breakpoint is set, it will be automatically updated
3697as shared libraries are loaded and unloaded.
3698
3699@cindex automatic hardware breakpoints
3700For some targets, @value{GDBN} can automatically decide if hardware or
3701software breakpoints should be used, depending on whether the
3702breakpoint address is read-only or read-write. This applies to
3703breakpoints set with the @code{break} command as well as to internal
3704breakpoints set by commands like @code{next} and @code{finish}. For
3705breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
3706breakpoints.
3707
3708You 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
3714This is the default behavior. When @value{GDBN} sets a breakpoint, it
3715will try to use the target memory map to decide if software or hardware
3716breakpoint must be used.
3717
3718@item set breakpoint auto-hw off
3719This indicates @value{GDBN} should not automatically select breakpoint
3720type. If the target provides a memory map, @value{GDBN} will warn when
3721trying to set software breakpoint at a read-only address.
3722@end table
3723
3724@value{GDBN} normally implements breakpoints by replacing the program code
3725at the breakpoint address with a special instruction, which, when
3726executed, given control to the debugger. By default, the program
3727code is so modified only when the program is resumed. As soon as
3728the program stops, @value{GDBN} restores the original instructions. This
3729behaviour guards against leaving breakpoints inserted in the
3730target should gdb abrubptly disconnect. However, with slow remote
3731targets, inserting and removing breakpoint can reduce the performance.
3732This 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
3738All breakpoints, including newly added by the user, are inserted in
3739the target only when the target is resumed. All breakpoints are
3740removed from the target when it stops.
3741
3742@item set breakpoint always-inserted on
3743Causes all breakpoints to be inserted in the target at all times. If
3744the user adds a new breakpoint, or changes an existing breakpoint, the
3745breakpoints in the target are updated immediately. A breakpoint is
3746removed 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
3750This is the default mode. If @value{GDBN} is controlling the inferior
3751in non-stop mode (@pxref{Non-Stop Mode}), gdb behaves as if
3752@code{breakpoint always-inserted} mode is on. If @value{GDBN} is
3753controlling the inferior in all-stop mode, @value{GDBN} behaves as if
3754@code{breakpoint always-inserted} mode is off.
3755@end table
3756
ef5ccd6c
JM
3757@value{GDBN} handles conditional breakpoints by evaluating these conditions
3758when a breakpoint breaks. If the condition is true, then the process being
3759debugged stops, otherwise the process is resumed.
3760
3761If the target supports evaluating conditions on its end, @value{GDBN} may
3762download the breakpoint, together with its conditions, to it.
3763
3764This 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
3770This option commands @value{GDBN} to evaluate the breakpoint
3771conditions on the host's side. Unconditional breakpoints are sent to
3772the target which in turn receives the triggers and reports them back to GDB
3773for condition evaluation. This is the standard evaluation mode.
3774
3775@item set breakpoint condition-evaluation target
3776This option commands @value{GDBN} to download breakpoint conditions
3777to the target at the moment of their insertion. The target
3778is responsible for evaluating the conditional expression and reporting
3779breakpoint stop events back to @value{GDBN} whenever the condition
3780is true. Due to limitations of target-side evaluation, some conditions
3781cannot be evaluated there, e.g., conditions that depend on local data
3782that is only known to the host. Examples include
3783conditional expressions involving convenience variables, complex types
3784that cannot be handled by the agent expression parser and expressions
3785that are too long to be sent over to the target, specially when the
3786target