1GDB(1) GNU Development Tools GDB(1)
2
6 gdb - The GNU Debugger
7
9 gdb [OPTIONS] [prog|prog procID|prog core]
10
12 The purpose of a debugger such as GDB is to allow you to see what is
13 going on "inside" another program while it executes -- or what another
14 program was doing at the moment it crashed.
15 GDB can do four main kinds of things (plus other things in support of
17 these) to help you catch bugs in the act:
18 • Start your program, specifying anything that might affect its
20 behavior.
21 • Make your program stop on specified conditions.
23 • Examine what has happened, when your program has stopped.
25 • Change things in your program, so you can experiment with
27 correcting the effects of one bug and go on to learn about another.
28 You can use GDB to debug programs written in C, C++, Fortran and
30 Modula-2.
31 GDB is invoked with the shell command "gdb". Once started, it reads
33 commands from the terminal until you tell it to exit with the GDB
34 command "quit". You can get online help from GDB itself by using the
35 command "help".
36 You can run "gdb" with no arguments or options; but the most usual way
38 to start GDB is with one argument or two, specifying an executable
39 program as the argument:
40 gdb program
42 You can also start with both an executable program and a core file
44 specified:
45 gdb program core
47 You can, instead, specify a process ID as a second argument or use
49 option "-p", if you want to debug a running process:
50 gdb program 1234
52 gdb -p 1234
53 would attach GDB to process 1234. With option -p you can omit the
55 program filename.
56 Here are some of the most frequently needed GDB commands:
58 break [file:][function|line]
60 Set a breakpoint at function or line (in file).
61 run [arglist]
63 Start your program (with arglist, if specified).
64 bt Backtrace: display the program stack.
66 print expr
68 Display the value of an expression.
69 c Continue running your program (after stopping, e.g. at a
71 breakpoint).
72 next
74 Execute next program line (after stopping); step over any function
75 calls in the line.
76 edit [file:]function
78 look at the program line where it is presently stopped.
79 list [file:]function
81 type the text of the program in the vicinity of where it is
82 presently stopped.
83 step
85 Execute next program line (after stopping); step into any function
86 calls in the line.
87 help [name]
89 Show information about GDB command name, or general information
90 about using GDB.
91 quit
93 Exit from GDB.
94 For full details on GDB, see Using GDB: A Guide to the GNU Source-Level
96 Debugger, by Richard M. Stallman and Roland H. Pesch. The same text is
97 available online as the "gdb" entry in the "info" program.
98
100 Any arguments other than options specify an executable file and core
101 file (or process ID); that is, the first argument encountered with no
102 associated option flag is equivalent to a --se option, and the second,
103 if any, is equivalent to a -c option if it's the name of a file. Many
104 options have both long and abbreviated forms; both are shown here. The
105 long forms are also recognized if you truncate them, so long as enough
106 of the option is present to be unambiguous.
107 The abbreviated forms are shown here with - and long forms are shown
109 with -- to reflect how they are shown in --help. However, GDB
110 recognizes all of the following conventions for most options:
111 "--option=value"
113 "--option value"
114 "-option=value"
115 "-option value"
116 "--o=value"
117 "--o value"
118 "-o=value"
119 "-o value"
120 All the options and command line arguments you give are processed in
122 sequential order. The order makes a difference when the -x option is
123 used.
124 --help
126 -h List all options, with brief explanations.
127 --symbols=file
129 -s file
130 Read symbol table from file.
131 --write
133 Enable writing into executable and core files.
134 --exec=file
136 -e file
137 Use file as the executable file to execute when appropriate, and
138 for examining pure data in conjunction with a core dump.
139 --se=file
141 Read symbol table from file and use it as the executable file.
142 --core=file
144 -c file
145 Use file as a core dump to examine.
146 --command=file
148 -x file
149 Execute GDB commands from file.
150 --eval-command=command
152 -ex command
153 Execute given GDB command.
154 --init-eval-command=command
156 -iex
157 Execute GDB command before loading the inferior.
158 --directory=directory
160 -d directory
161 Add directory to the path to search for source files.
162 --nh
164 Do not execute commands from ~/.config/gdb/gdbinit, ~/.gdbinit,
165 ~/.config/gdb/gdbearlyinit, or ~/.gdbearlyinit
166 --nx
168 -n Do not execute commands from any .gdbinit or .gdbearlyinit
169 initialization files.
170 --quiet
172 --silent
173 -q "Quiet". Do not print the introductory and copyright messages.
174 These messages are also suppressed in batch mode.
175 --batch
177 Run in batch mode. Exit with status 0 after processing all the
178 command files specified with -x (and .gdbinit, if not inhibited).
179 Exit with nonzero status if an error occurs in executing the GDB
180 commands in the command files.
181 Batch mode may be useful for running GDB as a filter, for example
183 to download and run a program on another computer; in order to make
184 this more useful, the message
185 Program exited normally.
187 (which is ordinarily issued whenever a program running under GDB
189 control terminates) is not issued when running in batch mode.
190 --batch-silent
192 Run in batch mode, just like --batch, but totally silent. All GDB
193 output is supressed (stderr is unaffected). This is much quieter
194 than --silent and would be useless for an interactive session.
195 This is particularly useful when using targets that give Loading
197 section messages, for example.
198 Note that targets that give their output via GDB, as opposed to
200 writing directly to "stdout", will also be made silent.
201 --args prog [arglist]
203 Change interpretation of command line so that arguments following
204 this option are passed as arguments to the inferior. As an
205 example, take the following command:
206 gdb ./a.out -q
208 It would start GDB with -q, not printing the introductory message.
210 On the other hand, using:
211 gdb --args ./a.out -q
213 starts GDB with the introductory message, and passes the option to
215 the inferior.
216 --pid=pid
218 Attach GDB to an already running program, with the PID pid.
219 --tui
221 Open the terminal user interface.
222 --readnow
224 Read all symbols from the given symfile on the first access.
225 --readnever
227 Do not read symbol files.
228 --dbx
230 Run in DBX compatibility mode.
231 --return-child-result
233 GDB's exit code will be the same as the child's exit code.
234 --configuration
236 Print details about GDB configuration and then exit.
237 --version
239 Print version information and then exit.
240 --cd=directory
242 Run GDB using directory as its working directory, instead of the
243 current directory.
244 --data-directory=directory
246 -D Run GDB using directory as its data directory. The data directory
247 is where GDB searches for its auxiliary files.
248 --fullname
250 -f Emacs sets this option when it runs GDB as a subprocess. It tells
251 GDB to output the full file name and line number in a standard,
252 recognizable fashion each time a stack frame is displayed (which
253 includes each time the program stops). This recognizable format
254 looks like two \032 characters, followed by the file name, line
255 number and character position separated by colons, and a newline.
256 The Emacs-to-GDB interface program uses the two \032 characters as
257 a signal to display the source code for the frame.
258 -b baudrate
260 Set the line speed (baud rate or bits per second) of any serial
261 interface used by GDB for remote debugging.
262 -l timeout
264 Set timeout, in seconds, for remote debugging.
265 --tty=device
267 Run using device for your program's standard input and output.
268
270 The full documentation for GDB is maintained as a Texinfo manual. If
271 the "info" and "gdb" programs and GDB's Texinfo documentation are
272 properly installed at your site, the command
273 info gdb
275 should give you access to the complete manual.
277 Using GDB: A Guide to the GNU Source-Level Debugger, Richard M.
279 Stallman and Roland H. Pesch, July 1991.
280
282 Copyright (c) 1988-2021 Free Software Foundation, Inc.
283 Permission is granted to copy, distribute and/or modify this document
285 under the terms of the GNU Free Documentation License, Version 1.3 or
286 any later version published by the Free Software Foundation; with the
287 Invariant Sections being "Free Software" and "Free Software Needs Free
288 Documentation", with the Front-Cover Texts being "A GNU Manual," and
289 with the Back-Cover Texts as in (a) below.
290 (a) The FSF's Back-Cover Text is: "You are free to copy and modify this
292 GNU Manual. Buying copies from GNU Press supports the FSF in
293 developing GNU and promoting software freedom."
294gdb-Fedora 11.1-5.fc35 2021-11-10 GDB(1)