1 .\" Copyright (c) 1991 Free Software Foundation
2 .\" See section COPYING for conditions for redistribution
3 .\" $FreeBSD: src/gnu/usr.bin/binutils/gdb/gdb.1,v 1.7 1999/08/27 23:34:49 peter Exp $
4 .\" $DragonFly: src/gnu/usr.bin/binutils/gdb/Attic/gdb.1,v 1.2 2003/06/17 04:25:44 dillon Exp $
5 .TH gdb 1 "4nov1991" "GNU Tools" "GNU Tools"
7 gdb \- The GNU Debugger
12 .RB "[\|" \-help "\|]"
15 .RB "[\|" \-batch "\|]"
21 .RB "[\|" \-wcore "\|]"
47 .IR core \||\| procID\c
51 The purpose of a debugger such as GDB is to allow you to see what is
52 going on ``inside'' another program while it executes\(em\&or what another
53 program was doing at the moment it crashed.
55 GDB can do four main kinds of things (plus other things in support of
56 these) to help you catch bugs in the act:
60 Start your program, specifying anything that might affect its behavior.
64 Make your program stop on specified conditions.
68 Examine what has happened, when your program has stopped.
72 Change things in your program, so you can experiment with correcting the
73 effects of one bug and go on to learn about another.
76 You can use GDB to debug programs written in C, C++, and Modula-2.
77 Fortran support will be added when a GNU Fortran compiler is ready.
79 GDB is invoked with the shell command \c
81 \&. Once started, it reads
82 commands from the terminal until you tell it to exit with the GDB
85 \&. You can get online help from \c
88 by using the command \c
94 \& with no arguments or options; but the most
95 usual way to start GDB is with one argument or two, specifying an
96 executable program as the argument:
103 You can also start with both an executable program and a core file specified:
110 You can, instead, specify a process ID as a second argument, if you want
111 to debug a running process:
118 would attach GDB to process \c
120 \& (unless you also have a file
123 \&\|'; GDB does check for a core file first).
125 Here are some of the most frequently needed GDB commands:
127 .B break \fR[\|\fIfile\fB:\fR\|]\fIfunction
129 Set a breakpoint at \c
135 .B run \fR[\|\fIarglist\fR\|]
136 Start your program (with \c
141 Backtrace: display the program stack.
145 Display the value of an expression.
148 Continue running your program (after stopping, e.g. at a breakpoint).
151 Execute next program line (after stopping); step \c
154 function calls in the line.
157 Execute next program line (after stopping); step \c
160 function calls in the line.
162 .B help \fR[\|\fIname\fR\|]
163 Show information about GDB command \c
165 \&, or general information
171 For full details on GDB, see \c
173 Using GDB: A Guide to the GNU Source-Level Debugger\c
174 \&, by Richard M. Stallman and Roland H. Pesch. The same text is available online
181 Any arguments other than options specify an executable
182 file and core file (or process ID); that is, the first argument
184 associated option flag is equivalent to a `\|\c
186 \&\|' option, and the
187 second, if any, is equivalent to a `\|\c
189 \&\|' option if it's the name of a file. Many options have
190 both long and short forms; both are shown here. The long forms are also
191 recognized if you truncate them, so long as enough of the option is
192 present to be unambiguous. (If you prefer, you can flag option
195 \&\|' rather than `\|\c
197 \&\|', though we illustrate the
198 more usual convention.)
200 All the options and command line arguments you give are processed
201 in sequential order. The order makes a difference when the
204 \&\|' option is used.
210 List all options, with brief explanations.
213 .BI "\-symbols=" "file"\c
217 Read symbol table from file \c
222 .BI "\-exec=" "file"\c
228 \& as the executable file to execute when
229 appropriate, and for examining pure data in conjunction with a core
235 Read symbol table from file \c
237 \& and use it as the executable
241 .BI "\-core=" "file"\c
247 \& as a core dump to examine.
250 .BI "\-command=" "file"\c
254 Execute GDB commands from file \c
259 .BI "\-directory=" "directory"\c
261 .BI "\-d " "directory"\c
265 \& to the path to search for source files.
272 Do not execute commands from any `\|\c
274 \&\|' initialization files.
275 Normally, the commands in these files are executed after all the
276 command options and arguments have been processed.
283 ``Quiet''. Do not print the introductory and copyright messages. These
284 messages are also suppressed in batch mode.
288 Run in batch mode. Exit with status \c
290 \& after processing all the command
291 files specified with `\|\c
295 \&\|', if not inhibited).
296 Exit with nonzero status if an error occurs in executing the GDB
297 commands in the command files.
299 Batch mode may be useful for running GDB as a filter, for example to
300 download and run a program on another computer; in order to make this
301 more useful, the message
304 Program\ exited\ normally.
308 (which is ordinarily issued whenever a program running under GDB control
309 terminates) is not issued when running in batch mode.
312 .BI "\-cd=" "directory"\c
316 \& as its working directory,
317 instead of the current directory.
323 Emacs sets this option when it runs GDB as a subprocess. It tells GDB
324 to output the full file name and line number in a standard,
325 recognizable fashion each time a stack frame is displayed (which
326 includes each time the program stops). This recognizable format looks
329 \&\|' characters, followed by the file name, line number
330 and character position separated by colons, and a newline. The
331 Emacs-to-GDB interface program uses the two `\|\c
334 a signal to display the source code for the frame.
340 Use gdb in kernel debugging mode. The prompt is set to ``(kgdb)''.
344 This option may only be used in kernel debugging mode while
345 debugging a ``live'' kernel and makes the corefile (/dev/mem)
351 Set the line speed (baud rate or bits per second) of any serial
352 interface used by GDB for remote debugging.
355 .BI "\-tty=" "device"\c
359 \& for your program's standard input and output.
368 Using GDB: A Guide to the GNU Source-Level Debugger\c
369 , Richard M. Stallman and Roland H. Pesch, July 1991.
371 Copyright (c) 1991 Free Software Foundation, Inc.
373 Permission is granted to make and distribute verbatim copies of
374 this manual provided the copyright notice and this permission notice
375 are preserved on all copies.
377 Permission is granted to copy and distribute modified versions of this
378 manual under the conditions for verbatim copying, provided that the
379 entire resulting derived work is distributed under the terms of a
380 permission notice identical to this one.
382 Permission is granted to copy and distribute translations of this
383 manual into another language, under the above conditions for modified
384 versions, except that this permission notice may be included in
385 translations approved by the Free Software Foundation instead of in
386 the original English.