| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" |
| 56 |
.\" Required to disable full justification in groff 1.23.0. |
| 57 |
.if n .ds AD l |
| 58 |
.\" ======================================================================== |
| 59 |
.\" |
| 60 |
.IX Title "GDB 1" |
| 61 |
.TH GDB 1 2026-04-21 gdb-16.3 "GNU Development Tools" |
| 62 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 63 |
.\" way too many mistakes in technical documents. |
| 64 |
.if n .ad l |
| 65 |
.nh |
| 66 |
.SH NAME |
| 67 |
gdb \- The GNU Debugger |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
gdb [OPTIONS] [\fIprog\fR|\fIprog\fR \fIprocID\fR|\fIprog\fR \fIcore\fR] |
| 71 |
.SH DESCRIPTION |
| 72 |
.IX Header "DESCRIPTION" |
| 73 |
The purpose of a debugger such as GDB is to allow you to see what is |
| 74 |
going on "inside" another program while it executes \-\- or what another |
| 75 |
program was doing at the moment it crashed. |
| 76 |
.PP |
| 77 |
GDB can do four main kinds of things (plus other things in support of |
| 78 |
these) to help you catch bugs in the act: |
| 79 |
.IP \(bu 4 |
| 80 |
Start your program, specifying anything that might affect its behavior. |
| 81 |
.IP \(bu 4 |
| 82 |
Make your program stop on specified conditions. |
| 83 |
.IP \(bu 4 |
| 84 |
Examine what has happened, when your program has stopped. |
| 85 |
.IP \(bu 4 |
| 86 |
Change things in your program, so you can experiment with correcting the |
| 87 |
effects of one bug and go on to learn about another. |
| 88 |
.PP |
| 89 |
You can use GDB to debug programs written in C, C++, Fortran and |
| 90 |
Modula\-2. |
| 91 |
.PP |
| 92 |
GDB is invoked with the shell command \f(CW\*(C`gdb\*(C'\fR. Once started, it reads |
| 93 |
commands from the terminal until you tell it to exit with the GDB |
| 94 |
command \f(CW\*(C`quit\*(C'\fR or \f(CW\*(C`exit\*(C'\fR. You can get online help from GDB itself |
| 95 |
by using the command \f(CW\*(C`help\*(C'\fR. |
| 96 |
.PP |
| 97 |
You can run \f(CW\*(C`gdb\*(C'\fR with no arguments or options; but the most |
| 98 |
usual way to start GDB is with one argument or two, specifying an |
| 99 |
executable program as the argument: |
| 100 |
.PP |
| 101 |
.Vb 1 |
| 102 |
\& gdb program |
| 103 |
.Ve |
| 104 |
.PP |
| 105 |
You can also start with both an executable program and a core file specified: |
| 106 |
.PP |
| 107 |
.Vb 1 |
| 108 |
\& gdb program core |
| 109 |
.Ve |
| 110 |
.PP |
| 111 |
You can, instead, specify a process ID as a second argument or use option |
| 112 |
\&\f(CW\*(C`\-p\*(C'\fR, if you want to debug a running process: |
| 113 |
.PP |
| 114 |
.Vb 2 |
| 115 |
\& gdb program 1234 |
| 116 |
\& gdb \-p 1234 |
| 117 |
.Ve |
| 118 |
.PP |
| 119 |
would attach GDB to process \f(CW1234\fR. With option \fB\-p\fR you |
| 120 |
can omit the \fIprogram\fR filename. |
| 121 |
.PP |
| 122 |
Here are some of the most frequently needed GDB commands: |
| 123 |
.IP "\fBbreak [\fR\fIfile\fR\fB:][\fR\fIfunction\fR\fB|\fR\fIline\fR\fB]\fR" 4 |
| 124 |
.IX Item "break [file:][function|line]" |
| 125 |
Set a breakpoint at \fIfunction\fR or \fIline\fR (in \fIfile\fR). |
| 126 |
.IP "\fBrun [\fR\fIarglist\fR\fB]\fR" 4 |
| 127 |
.IX Item "run [arglist]" |
| 128 |
Start your program (with \fIarglist\fR, if specified). |
| 129 |
.IP \fBbt\fR 4 |
| 130 |
.IX Item "bt" |
| 131 |
Backtrace: display the program stack. |
| 132 |
.IP "\fBprint\fR \fIexpr\fR" 4 |
| 133 |
.IX Item "print expr" |
| 134 |
Display the value of an expression. |
| 135 |
.IP \fBc\fR 4 |
| 136 |
.IX Item "c" |
| 137 |
Continue running your program (after stopping, e.g. at a breakpoint). |
| 138 |
.IP \fBnext\fR 4 |
| 139 |
.IX Item "next" |
| 140 |
Execute next program line (after stopping); step \fIover\fR any |
| 141 |
function calls in the line. |
| 142 |
.IP "\fBedit [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4 |
| 143 |
.IX Item "edit [file:]function" |
| 144 |
look at the program line where it is presently stopped. |
| 145 |
.IP "\fBlist [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4 |
| 146 |
.IX Item "list [file:]function" |
| 147 |
type the text of the program in the vicinity of where it is presently stopped. |
| 148 |
.IP \fBstep\fR 4 |
| 149 |
.IX Item "step" |
| 150 |
Execute next program line (after stopping); step \fIinto\fR any |
| 151 |
function calls in the line. |
| 152 |
.IP "\fBhelp [\fR\fIname\fR\fB]\fR" 4 |
| 153 |
.IX Item "help [name]" |
| 154 |
Show information about GDB command \fIname\fR, or general information |
| 155 |
about using GDB. |
| 156 |
.IP \fBquit\fR 4 |
| 157 |
.IX Item "quit" |
| 158 |
.PD 0 |
| 159 |
.IP \fBexit\fR 4 |
| 160 |
.IX Item "exit" |
| 161 |
.PD |
| 162 |
Exit from GDB. |
| 163 |
.PP |
| 164 |
For full details on GDB, |
| 165 |
see \fIUsing GDB: A Guide to the GNU Source\-Level Debugger\fR, |
| 166 |
by Richard M. Stallman and Roland H. Pesch. The same text is available online |
| 167 |
as the \f(CW\*(C`gdb\*(C'\fR entry in the \f(CW\*(C`info\*(C'\fR program. |
| 168 |
.SH OPTIONS |
| 169 |
.IX Header "OPTIONS" |
| 170 |
Any arguments other than options specify an executable |
| 171 |
file and core file (or process ID); that is, the first argument |
| 172 |
encountered with no |
| 173 |
associated option flag is equivalent to a \fB\-\-se\fR option, and the second, |
| 174 |
if any, is equivalent to a \fB\-c\fR option if it\*(Aqs the name of a file. |
| 175 |
Many options have |
| 176 |
both long and abbreviated forms; both are shown here. The long forms are also |
| 177 |
recognized if you truncate them, so long as enough of the option is |
| 178 |
present to be unambiguous. |
| 179 |
.PP |
| 180 |
The abbreviated forms are shown here with \fB\-\fR and long forms are shown |
| 181 |
with \fB\-\-\fR to reflect how they are shown in \fB\-\-help\fR. However, |
| 182 |
GDB recognizes all of the following conventions for most options: |
| 183 |
.ie n .IP """\-\-option=\fIvalue\fR""" 4 |
| 184 |
.el .IP \f(CW\-\-option=\fR\f(CIvalue\fR\f(CW\fR 4 |
| 185 |
.IX Item "--option=value" |
| 186 |
.PD 0 |
| 187 |
.ie n .IP """\-\-option \fIvalue\fR""" 4 |
| 188 |
.el .IP "\f(CW\-\-option \fR\f(CIvalue\fR\f(CW\fR" 4 |
| 189 |
.IX Item "--option value" |
| 190 |
.ie n .IP """\-option=\fIvalue\fR""" 4 |
| 191 |
.el .IP \f(CW\-option=\fR\f(CIvalue\fR\f(CW\fR 4 |
| 192 |
.IX Item "-option=value" |
| 193 |
.ie n .IP """\-option \fIvalue\fR""" 4 |
| 194 |
.el .IP "\f(CW\-option \fR\f(CIvalue\fR\f(CW\fR" 4 |
| 195 |
.IX Item "-option value" |
| 196 |
.ie n .IP """\-\-o=\fIvalue\fR""" 4 |
| 197 |
.el .IP \f(CW\-\-o=\fR\f(CIvalue\fR\f(CW\fR 4 |
| 198 |
.IX Item "--o=value" |
| 199 |
.ie n .IP """\-\-o \fIvalue\fR""" 4 |
| 200 |
.el .IP "\f(CW\-\-o \fR\f(CIvalue\fR\f(CW\fR" 4 |
| 201 |
.IX Item "--o value" |
| 202 |
.ie n .IP """\-o=\fIvalue\fR""" 4 |
| 203 |
.el .IP \f(CW\-o=\fR\f(CIvalue\fR\f(CW\fR 4 |
| 204 |
.IX Item "-o=value" |
| 205 |
.ie n .IP """\-o \fIvalue\fR""" 4 |
| 206 |
.el .IP "\f(CW\-o \fR\f(CIvalue\fR\f(CW\fR" 4 |
| 207 |
.IX Item "-o value" |
| 208 |
.PD |
| 209 |
.PP |
| 210 |
All the options and command line arguments you give are processed |
| 211 |
in sequential order. The order makes a difference when the \fB\-x\fR |
| 212 |
option is used. |
| 213 |
.IP \fB\-\-help\fR 4 |
| 214 |
.IX Item "--help" |
| 215 |
.PD 0 |
| 216 |
.IP \fB\-h\fR 4 |
| 217 |
.IX Item "-h" |
| 218 |
.PD |
| 219 |
List all options, with brief explanations. |
| 220 |
.IP \fB\-\-symbols=\fR\fIfile\fR 4 |
| 221 |
.IX Item "--symbols=file" |
| 222 |
.PD 0 |
| 223 |
.IP "\fB\-s\fR \fIfile\fR" 4 |
| 224 |
.IX Item "-s file" |
| 225 |
.PD |
| 226 |
Read symbol table from \fIfile\fR. |
| 227 |
.IP \fB\-\-write\fR 4 |
| 228 |
.IX Item "--write" |
| 229 |
Enable writing into executable and core files. |
| 230 |
.IP \fB\-\-exec=\fR\fIfile\fR 4 |
| 231 |
.IX Item "--exec=file" |
| 232 |
.PD 0 |
| 233 |
.IP "\fB\-e\fR \fIfile\fR" 4 |
| 234 |
.IX Item "-e file" |
| 235 |
.PD |
| 236 |
Use \fIfile\fR as the executable file to execute when |
| 237 |
appropriate, and for examining pure data in conjunction with a core |
| 238 |
dump. |
| 239 |
.IP \fB\-\-se=\fR\fIfile\fR 4 |
| 240 |
.IX Item "--se=file" |
| 241 |
Read symbol table from \fIfile\fR and use it as the executable |
| 242 |
file. |
| 243 |
.IP \fB\-\-core=\fR\fIfile\fR 4 |
| 244 |
.IX Item "--core=file" |
| 245 |
.PD 0 |
| 246 |
.IP "\fB\-c\fR \fIfile\fR" 4 |
| 247 |
.IX Item "-c file" |
| 248 |
.PD |
| 249 |
Use \fIfile\fR as a core dump to examine. |
| 250 |
.IP \fB\-\-command=\fR\fIfile\fR 4 |
| 251 |
.IX Item "--command=file" |
| 252 |
.PD 0 |
| 253 |
.IP "\fB\-x\fR \fIfile\fR" 4 |
| 254 |
.IX Item "-x file" |
| 255 |
.PD |
| 256 |
Execute GDB commands from \fIfile\fR. |
| 257 |
.IP \fB\-\-eval\-command=\fR\fIcommand\fR 4 |
| 258 |
.IX Item "--eval-command=command" |
| 259 |
.PD 0 |
| 260 |
.IP "\fB\-ex\fR \fIcommand\fR" 4 |
| 261 |
.IX Item "-ex command" |
| 262 |
.PD |
| 263 |
Execute given GDB \fIcommand\fR. |
| 264 |
.IP \fB\-\-init\-eval\-command=\fR\fIcommand\fR 4 |
| 265 |
.IX Item "--init-eval-command=command" |
| 266 |
.PD 0 |
| 267 |
.IP \fB\-iex\fR 4 |
| 268 |
.IX Item "-iex" |
| 269 |
.PD |
| 270 |
Execute GDB \fIcommand\fR before loading the inferior. |
| 271 |
.IP \fB\-\-directory=\fR\fIdirectory\fR 4 |
| 272 |
.IX Item "--directory=directory" |
| 273 |
.PD 0 |
| 274 |
.IP "\fB\-d\fR \fIdirectory\fR" 4 |
| 275 |
.IX Item "-d directory" |
| 276 |
.PD |
| 277 |
Add \fIdirectory\fR to the path to search for source files. |
| 278 |
.IP \fB\-\-nh\fR 4 |
| 279 |
.IX Item "--nh" |
| 280 |
Do not execute commands from \fI~/.config/gdb/gdbinit\fR, |
| 281 |
\&\fI~/.gdbinit\fR, \fI~/.config/gdb/gdbearlyinit\fR, or |
| 282 |
\&\fI~/.gdbearlyinit\fR |
| 283 |
.IP \fB\-\-nx\fR 4 |
| 284 |
.IX Item "--nx" |
| 285 |
.PD 0 |
| 286 |
.IP \fB\-n\fR 4 |
| 287 |
.IX Item "-n" |
| 288 |
.PD |
| 289 |
Do not execute commands from any \fI.gdbinit\fR or |
| 290 |
\&\fI.gdbearlyinit\fR initialization files. |
| 291 |
.IP \fB\-\-quiet\fR 4 |
| 292 |
.IX Item "--quiet" |
| 293 |
.PD 0 |
| 294 |
.IP \fB\-\-silent\fR 4 |
| 295 |
.IX Item "--silent" |
| 296 |
.IP \fB\-q\fR 4 |
| 297 |
.IX Item "-q" |
| 298 |
.PD |
| 299 |
"Quiet". Do not print the introductory and copyright messages. These |
| 300 |
messages are also suppressed in batch mode. |
| 301 |
.IP \fB\-\-batch\fR 4 |
| 302 |
.IX Item "--batch" |
| 303 |
Run in batch mode. Exit with status \f(CW0\fR after processing all the command |
| 304 |
files specified with \fB\-x\fR (and \fI.gdbinit\fR, if not inhibited). |
| 305 |
Exit with nonzero status if an error occurs in executing the GDB |
| 306 |
commands in the command files. |
| 307 |
.Sp |
| 308 |
Batch mode may be useful for running GDB as a filter, for example to |
| 309 |
download and run a program on another computer; in order to make this |
| 310 |
more useful, the message |
| 311 |
.Sp |
| 312 |
.Vb 1 |
| 313 |
\& Program exited normally. |
| 314 |
.Ve |
| 315 |
.Sp |
| 316 |
(which is ordinarily issued whenever a program running under GDB control |
| 317 |
terminates) is not issued when running in batch mode. |
| 318 |
.IP \fB\-\-batch\-silent\fR 4 |
| 319 |
.IX Item "--batch-silent" |
| 320 |
Run in batch mode, just like \fB\-\-batch\fR, but totally silent. All GDB |
| 321 |
output is suppressed (stderr is unaffected). This is much quieter than |
| 322 |
\&\fB\-\-silent\fR and would be useless for an interactive session. |
| 323 |
.Sp |
| 324 |
This is particularly useful when using targets that give \fBLoading section\fR |
| 325 |
messages, for example. |
| 326 |
.Sp |
| 327 |
Note that targets that give their output via GDB, as opposed to writing |
| 328 |
directly to \f(CW\*(C`stdout\*(C'\fR, will also be made silent. |
| 329 |
.IP "\fB\-\-args\fR \fIprog\fR \fB[\fR\fIarglist\fR\fB]\fR" 4 |
| 330 |
.IX Item "--args prog [arglist]" |
| 331 |
Change interpretation of command line so that arguments following this |
| 332 |
option are passed as arguments to the inferior. As an example, take |
| 333 |
the following command: |
| 334 |
.Sp |
| 335 |
.Vb 1 |
| 336 |
\& gdb ./a.out \-q |
| 337 |
.Ve |
| 338 |
.Sp |
| 339 |
It would start GDB with \fB\-q\fR, not printing the introductory message. On |
| 340 |
the other hand, using: |
| 341 |
.Sp |
| 342 |
.Vb 1 |
| 343 |
\& gdb \-\-args ./a.out \-q |
| 344 |
.Ve |
| 345 |
.Sp |
| 346 |
starts GDB with the introductory message, and passes the option to the inferior. |
| 347 |
.IP \fB\-\-pid=\fR\fIpid\fR 4 |
| 348 |
.IX Item "--pid=pid" |
| 349 |
Attach GDB to an already running program, with the PID \fIpid\fR. |
| 350 |
.IP \fB\-\-tui\fR 4 |
| 351 |
.IX Item "--tui" |
| 352 |
Open the terminal user interface. |
| 353 |
.IP \fB\-\-readnow\fR 4 |
| 354 |
.IX Item "--readnow" |
| 355 |
Read all symbols from the given symfile on the first access. |
| 356 |
.IP \fB\-\-readnever\fR 4 |
| 357 |
.IX Item "--readnever" |
| 358 |
Do not read symbol files. |
| 359 |
.IP \fB\-\-return\-child\-result\fR 4 |
| 360 |
.IX Item "--return-child-result" |
| 361 |
GDB\*(Aqs exit code will be the same as the child\*(Aqs exit code. |
| 362 |
.IP \fB\-\-configuration\fR 4 |
| 363 |
.IX Item "--configuration" |
| 364 |
Print details about GDB configuration and then exit. |
| 365 |
.IP \fB\-\-version\fR 4 |
| 366 |
.IX Item "--version" |
| 367 |
Print version information and then exit. |
| 368 |
.IP \fB\-\-cd=\fR\fIdirectory\fR 4 |
| 369 |
.IX Item "--cd=directory" |
| 370 |
Run GDB using \fIdirectory\fR as its working directory, |
| 371 |
instead of the current directory. |
| 372 |
.IP \fB\-\-data\-directory=\fR\fIdirectory\fR 4 |
| 373 |
.IX Item "--data-directory=directory" |
| 374 |
.PD 0 |
| 375 |
.IP \fB\-D\fR 4 |
| 376 |
.IX Item "-D" |
| 377 |
.PD |
| 378 |
Run GDB using \fIdirectory\fR as its data directory. The data |
| 379 |
directory is where GDB searches for its auxiliary files. |
| 380 |
.IP \fB\-\-fullname\fR 4 |
| 381 |
.IX Item "--fullname" |
| 382 |
.PD 0 |
| 383 |
.IP \fB\-f\fR 4 |
| 384 |
.IX Item "-f" |
| 385 |
.PD |
| 386 |
Emacs sets this option when it runs GDB as a subprocess. It tells |
| 387 |
GDB to output the full file name and line number in a standard, |
| 388 |
recognizable fashion each time a stack frame is displayed (which |
| 389 |
includes each time the program stops). This recognizable format looks |
| 390 |
like two \fB\e032\fR characters, followed by the file name, line number |
| 391 |
and character position separated by colons, and a newline. The |
| 392 |
Emacs\-to\-GDB interface program uses the two \fB\e032\fR |
| 393 |
characters as a signal to display the source code for the frame. |
| 394 |
.IP "\fB\-b\fR \fIbaudrate\fR" 4 |
| 395 |
.IX Item "-b baudrate" |
| 396 |
Set the line speed (baud rate or bits per second) of any serial |
| 397 |
interface used by GDB for remote debugging. |
| 398 |
.IP "\fB\-l\fR \fItimeout\fR" 4 |
| 399 |
.IX Item "-l timeout" |
| 400 |
Set timeout, in seconds, for remote debugging. |
| 401 |
.IP \fB\-\-tty=\fR\fIdevice\fR 4 |
| 402 |
.IX Item "--tty=device" |
| 403 |
Run using \fIdevice\fR for your program\*(Aqs standard input and output. |
| 404 |
.SH ENVIRONMENT |
| 405 |
.IX Header "ENVIRONMENT" |
| 406 |
.SH "SEE ALSO" |
| 407 |
.IX Header "SEE ALSO" |
| 408 |
The full documentation for GDB is maintained as a Texinfo manual. |
| 409 |
If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and GDB\*(Aqs Texinfo |
| 410 |
documentation are properly installed at your site, the command |
| 411 |
.PP |
| 412 |
.Vb 1 |
| 413 |
\& info gdb |
| 414 |
.Ve |
| 415 |
.PP |
| 416 |
should give you access to the complete manual. |
| 417 |
.PP |
| 418 |
\&\fIUsing GDB: A Guide to the GNU Source\-Level Debugger\fR, |
| 419 |
Richard M. Stallman and Roland H. Pesch, July 1991. |
| 420 |
.SH COPYRIGHT |
| 421 |
.IX Header "COPYRIGHT" |
| 422 |
Copyright (c) 1988\-2024 Free Software Foundation, Inc. |
| 423 |
.PP |
| 424 |
Permission is granted to copy, distribute and/or modify this document |
| 425 |
under the terms of the GNU Free Documentation License, Version 1.3 or |
| 426 |
any later version published by the Free Software Foundation; with the |
| 427 |
Invariant Sections being "Free Software" and "Free Software Needs |
| 428 |
Free Documentation", with the Front\-Cover Texts being "A GNU Manual," |
| 429 |
and with the Back\-Cover Texts as in (a) below. |
| 430 |
.PP |
| 431 |
(a) The FSF\*(Aqs Back\-Cover Text is: "You are free to copy and modify |
| 432 |
this GNU Manual. Buying copies from GNU Press supports the FSF in |
| 433 |
developing GNU and promoting software freedom." |