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" or "exit". You can get online help from GDB itself by
35 using the 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
94 Exit from GDB.
95 For full details on GDB, see Using GDB: A Guide to the GNU Source-Level
97 Debugger, by Richard M. Stallman and Roland H. Pesch. The same text is
98 available online as the "gdb" entry in the "info" program.
99
101 Any arguments other than options specify an executable file and core
102 file (or process ID); that is, the first argument encountered with no
103 associated option flag is equivalent to a --se option, and the second,
104 if any, is equivalent to a -c option if it's the name of a file. Many
105 options have both long and abbreviated forms; both are shown here. The
106 long forms are also recognized if you truncate them, so long as enough
107 of the option is present to be unambiguous.
108 The abbreviated forms are shown here with - and long forms are shown
110 with -- to reflect how they are shown in --help. However, GDB
111 recognizes all of the following conventions for most options:
112 "--option=value"
114 "--option value"
115 "-option=value"
116 "-option value"
117 "--o=value"
118 "--o value"
119 "-o=value"
120 "-o value"
121 All the options and command line arguments you give are processed in
123 sequential order. The order makes a difference when the -x option is
124 used.
125 --help
127 -h List all options, with brief explanations.
128 --symbols=file
130 -s file
131 Read symbol table from file.
132 --write
134 Enable writing into executable and core files.
135 --exec=file
137 -e file
138 Use file as the executable file to execute when appropriate, and
139 for examining pure data in conjunction with a core dump.
140 --se=file
142 Read symbol table from file and use it as the executable file.
143 --core=file
145 -c file
146 Use file as a core dump to examine.
147 --command=file
149 -x file
150 Execute GDB commands from file.
151 --eval-command=command
153 -ex command
154 Execute given GDB command.
155 --init-eval-command=command
157 -iex
158 Execute GDB command before loading the inferior.
159 --directory=directory
161 -d directory
162 Add directory to the path to search for source files.
163 --nh
165 Do not execute commands from ~/.config/gdb/gdbinit, ~/.gdbinit,
166 ~/.config/gdb/gdbearlyinit, or ~/.gdbearlyinit
167 --nx
169 -n Do not execute commands from any .gdbinit or .gdbearlyinit
170 initialization files.
171 --quiet
173 --silent
174 -q "Quiet". Do not print the introductory and copyright messages.
175 These messages are also suppressed in batch mode.
176 --batch
178 Run in batch mode. Exit with status 0 after processing all the
179 command files specified with -x (and .gdbinit, if not inhibited).
180 Exit with nonzero status if an error occurs in executing the GDB
181 commands in the command files.
182 Batch mode may be useful for running GDB as a filter, for example
184 to download and run a program on another computer; in order to make
185 this more useful, the message
186 Program exited normally.
188 (which is ordinarily issued whenever a program running under GDB
190 control terminates) is not issued when running in batch mode.
191 --batch-silent
193 Run in batch mode, just like --batch, but totally silent. All GDB
194 output is suppressed (stderr is unaffected). This is much quieter
195 than --silent and would be useless for an interactive session.
196 This is particularly useful when using targets that give Loading
198 section messages, for example.
199 Note that targets that give their output via GDB, as opposed to
201 writing directly to "stdout", will also be made silent.
202 --args prog [arglist]
204 Change interpretation of command line so that arguments following
205 this option are passed as arguments to the inferior. As an
206 example, take the following command:
207 gdb ./a.out -q
209 It would start GDB with -q, not printing the introductory message.
211 On the other hand, using:
212 gdb --args ./a.out -q
214 starts GDB with the introductory message, and passes the option to
216 the inferior.
217 --pid=pid
219 Attach GDB to an already running program, with the PID pid.
220 --tui
222 Open the terminal user interface.
223 --readnow
225 Read all symbols from the given symfile on the first access.
226 --readnever
228 Do not read symbol files.
229 --return-child-result
231 GDB's exit code will be the same as the child's exit code.
232 --configuration
234 Print details about GDB configuration and then exit.
235 --version
237 Print version information and then exit.
238 --cd=directory
240 Run GDB using directory as its working directory, instead of the
241 current directory.
242 --data-directory=directory
244 -D Run GDB using directory as its data directory. The data directory
245 is where GDB searches for its auxiliary files.
246 --fullname
248 -f Emacs sets this option when it runs GDB as a subprocess. It tells
249 GDB to output the full file name and line number in a standard,
250 recognizable fashion each time a stack frame is displayed (which
251 includes each time the program stops). This recognizable format
252 looks like two \032 characters, followed by the file name, line
253 number and character position separated by colons, and a newline.
254 The Emacs-to-GDB interface program uses the two \032 characters as
255 a signal to display the source code for the frame.
256 -b baudrate
258 Set the line speed (baud rate or bits per second) of any serial
259 interface used by GDB for remote debugging.
260 -l timeout
262 Set timeout, in seconds, for remote debugging.
263 --tty=device
265 Run using device for your program's standard input and output.
266
268 The full documentation for GDB is maintained as a Texinfo manual. If
269 the "info" and "gdb" programs and GDB's Texinfo documentation are
270 properly installed at your site, the command
271 info gdb
273 should give you access to the complete manual.
275 Using GDB: A Guide to the GNU Source-Level Debugger, Richard M.
277 Stallman and Roland H. Pesch, July 1991.
278
280 Copyright (c) 1988-2023 Free Software Foundation, Inc.
281 Permission is granted to copy, distribute and/or modify this document
283 under the terms of the GNU Free Documentation License, Version 1.3 or
284 any later version published by the Free Software Foundation; with the
285 Invariant Sections being "Free Software" and "Free Software Needs Free
286 Documentation", with the Front-Cover Texts being "A GNU Manual," and
287 with the Back-Cover Texts as in (a) below.
288 (a) The FSF's Back-Cover Text is: "You are free to copy and modify this
290 GNU Manual. Buying copies from GNU Press supports the FSF in
291 developing GNU and promoting software freedom."
292gdb-14.1-1.fc39 2023-12-07 GDB(1)