gdb/gdb.1

   1 .\" Copyright (C) 1991, 1999, 2010-2012 Free Software Foundation, Inc.
   2 .\" See section COPYING for conditions for redistribution
   3 .\" $Id$
   4 .TH gdb 1 "22may2002" "GNU Tools" "GNU Tools"
   5 .SH NAME
   6 gdb \- The GNU Debugger
   7 .SH SYNOPSIS
   8 .na
   9 .TP
  10 .B gdb
  11 .RB "[\|" \-help "\|]"
  12 .RB "[\|" \-nx "\|]"
  13 .RB "[\|" \-q "\|]"
  14 .RB "[\|" \-batch "\|]"
  15 .RB "[\|" \-cd=\c
  16 .I dir\c
  17 \|]
  18 .RB "[\|" \-f "\|]"
  19 .RB "[\|" "\-b\ "\c
  20 .IR bps "\|]"
  21 .RB "[\|" "\-tty="\c
  22 .IR dev "\|]"
  23 .RB "[\|" "\-s "\c
  24 .I symfile\c
  25 \&\|]
  26 .RB "[\|" "\-e "\c
  27 .I prog\c
  28 \&\|]
  29 .RB "[\|" "\-se "\c
  30 .I prog\c
  31 \&\|]
  32 .RB "[\|" "\-c "\c
  33 .I core\c
  34 \&\|]
  35 .RB "[\|" "\-x "\c
  36 .I file\c
  37 \&\|]
  38 .RB "[\|" "\-ex "\c
  39 .I cmd\c
  40 \&\|]
  41 .RB "[\|" "\-d "\c
  42 .I dir\c
  43 \&\|]
  44 .RB "[\|" \c
  45 .I prog\c
  46 .RB "[\|" \c
  47 .IR core \||\| procID\c
  48 \&\|]\&\|]
  49 .ad b
  50 .SH DESCRIPTION
  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.
  54
  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:
  57
  58 .TP
  59 \ \ \ \(bu
  60 Start your program, specifying anything that might affect its behavior.
  61
  62 .TP
  63 \ \ \ \(bu
  64 Make your program stop on specified conditions.
  65
  66 .TP
  67 \ \ \ \(bu
  68 Examine what has happened, when your program has stopped.
  69
  70 .TP
  71 \ \ \ \(bu
  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.
  74 .PP
  75
  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.
  78
  79 GDB is invoked with the shell command \c
  80 .B gdb\c
  81 \&.  Once started, it reads
  82 commands from the terminal until you tell it to exit with the GDB
  83 command \c
  84 .B quit\c
  85 \&.  You can get online help from \c
  86 .B gdb\c
  87 \& itself
  88 by using the command \c
  89 .B help\c
  90 \&.
  91
  92 You can run \c
  93 .B gdb\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:
  97 .sp
  98 .br
  99 gdb\ program
 100 .br
 101 .sp
 102
 103 You can also start with both an executable program and a core file specified:
 104 .sp
 105 .br
 106 gdb\ program\ core
 107 .br
 108 .sp
 109
 110 You can, instead, specify a process ID as a second argument, if you want
 111 to debug a running process:
 112 .sp
 113 .br
 114 gdb\ program\ 1234
 115 .br
 116 .sp
 117
 118 would attach GDB to process \c
 119 .B 1234\c
 120 \& (unless you also have a file
 121 named `\|\c
 122 .B 1234\c
 123 \&\|'; GDB does check for a core file first).
 124
 125 Here are some of the most frequently needed GDB commands:
 126 .TP
 127 .B break \fR[\|\fIfile\fB:\fR\|]\fIfunction
 128 \&
 129 Set a breakpoint at \c
 130 .I function\c
 131 \& (in \c
 132 .I file\c
 133 \&).
 134 .TP
 135 .B run \fR[\|\fIarglist\fR\|]
 136 Start your program (with \c
 137 .I arglist\c
 138 \&, if specified).
 139 .TP
 140 .B bt
 141 Backtrace: display the program stack.
 142 .TP
 143 .BI print " expr"\c
 144 \&
 145 Display the value of an expression.
 146 .TP
 147 .B c
 148 Continue running your program (after stopping, e.g. at a breakpoint).
 149 .TP
 150 .B next
 151 Execute next program line (after stopping); step \c
 152 .I over\c
 153 \& any
 154 function calls in the line.
 155 .TP
 156 .B edit \fR[\|\fIfile\fB:\fR\|]\fIfunction
 157 look at the program line where it is presently stopped.
 158 .TP
 159 .B list \fR[\|\fIfile\fB:\fR\|]\fIfunction
 160 type the text of the program in the vicinity of where it is presently stopped.
 161 .TP
 162 .B step
 163 Execute next program line (after stopping); step \c
 164 .I into\c
 165 \& any
 166 function calls in the line.
 167 .TP
 168 .B help \fR[\|\fIname\fR\|]
 169 Show information about GDB command \c
 170 .I name\c
 171 \&, or general information
 172 about using GDB.
 173 .TP
 174 .B quit
 175 Exit from GDB.
 176 .PP
 177 For full details on GDB, see \c
 178 .I
 179 Using GDB: A Guide to the GNU Source-Level Debugger\c
 180 \&, by Richard M. Stallman and Roland H. Pesch.  The same text is available online
 181 as the \c
 182 .B gdb\c
 183 \& entry in the \c
 184 .B info\c
 185 \& program.
 186 .SH OPTIONS
 187 Any arguments other than options specify an executable
 188 file and core file (or process ID); that is, the first argument
 189 encountered with no
 190 associated option flag is equivalent to a `\|\c
 191 .B \-se\c
 192 \&\|' option, and the
 193 second, if any, is equivalent to a `\|\c
 194 .B \-c\c
 195 \&\|' option if it's the name of a file.  Many options have
 196 both long and short forms; both are shown here.  The long forms are also
 197 recognized if you truncate them, so long as enough of the option is
 198 present to be unambiguous.  (If you prefer, you can flag option
 199 arguments with `\|\c
 200 .B +\c
 201 \&\|' rather than `\|\c
 202 .B \-\c
 203 \&\|', though we illustrate the
 204 more usual convention.)
 205
 206 All the options and command line arguments you give are processed
 207 in sequential order.  The order makes a difference when the
 208 `\|\c
 209 .B \-x\c
 210 \&\|' option is used.
 211
 212 .TP
 213 .B \-help
 214 .TP
 215 .B \-h
 216 List all options, with brief explanations.
 217
 218 .TP
 219 .BI "\-symbols=" "file"\c
 220 .TP
 221 .BI "\-s " "file"\c
 222 \&
 223 Read symbol table from file \c
 224 .I file\c
 225 \&.
 226
 227 .TP
 228 .B \-write
 229 Enable writing into executable and core files.
 230
 231 .TP
 232 .BI "\-exec=" "file"\c
 233 .TP
 234 .BI "\-e " "file"\c
 235 \&
 236 Use file \c
 237 .I file\c
 238 \& as the executable file to execute when
 239 appropriate, and for examining pure data in conjunction with a core
 240 dump.
 241
 242 .TP
 243 .BI "\-se=" "file"\c
 244 \&
 245 Read symbol table from file \c
 246 .I file\c
 247 \& and use it as the executable
 248 file.
 249
 250 .TP
 251 .BI "\-core=" "file"\c
 252 .TP
 253 .BI "\-c " "file"\c
 254 \&
 255 Use file \c
 256 .I file\c
 257 \& as a core dump to examine.
 258
 259 .TP
 260 .BI "\-command=" "file"\c
 261 .TP
 262 .BI "\-x " "file"\c
 263 \&
 264 Execute GDB commands from file \c
 265 .I file\c
 266 \&.
 267
 268 .TP
 269 .BI "\-ex " "command"\c
 270 \&
 271 Execute given GDB \c
 272 .I command\c
 273 \&.
 274
 275 .TP
 276 .BI "\-directory=" "directory"\c
 277 .TP
 278 .BI "\-d " "directory"\c
 279 \&
 280 Add \c
 281 .I directory\c
 282 \& to the path to search for source files.
 283 .PP
 284
 285 .TP
 286 .B \-nx
 287 .TP
 288 .B \-n
 289 Do not execute commands from any `\|\c
 290 .B .gdbinit\c
 291 \&\|' initialization files.
 292 Normally, the commands in these files are executed after all the
 293 command options and arguments have been processed.
 294
 295
 296 .TP
 297 .B \-quiet
 298 .TP
 299 .B \-q
 300 ``Quiet''.  Do not print the introductory and copyright messages.  These
 301 messages are also suppressed in batch mode.
 302
 303 .TP
 304 .B \-batch
 305 Run in batch mode.  Exit with status \c
 306 .B 0\c
 307 \& after processing all the command
 308 files specified with `\|\c
 309 .B \-x\c
 310 \&\|' (and `\|\c
 311 .B .gdbinit\c
 312 \&\|', if not inhibited).
 313 Exit with nonzero status if an error occurs in executing the GDB
 314 commands in the command files.
 315
 316 Batch mode may be useful for running GDB as a filter, for example to
 317 download and run a program on another computer; in order to make this
 318 more useful, the message
 319 .sp
 320 .br
 321 Program\ exited\ normally.
 322 .br
 323 .sp
 324
 325 (which is ordinarily issued whenever a program running under GDB control
 326 terminates) is not issued when running in batch mode.
 327
 328 .TP
 329 .BI "\-cd=" "directory"\c
 330 \&
 331 Run GDB using \c
 332 .I directory\c
 333 \& as its working directory,
 334 instead of the current directory.
 335
 336 .TP
 337 .B \-fullname
 338 .TP
 339 .B \-f
 340 Emacs sets this option when it runs GDB as a subprocess.  It tells GDB
 341 to output the full file name and line number in a standard,
 342 recognizable fashion each time a stack frame is displayed (which
 343 includes each time the program stops).  This recognizable format looks
 344 like two `\|\c
 345 .B \032\c
 346 \&\|' characters, followed by the file name, line number
 347 and character position separated by colons, and a newline.  The
 348 Emacs-to-GDB interface program uses the two `\|\c
 349 .B \032\c
 350 \&\|' characters as
 351 a signal to display the source code for the frame.
 352
 353 .TP
 354 .BI "\-b " "bps"\c
 355 \&
 356 Set the line speed (baud rate or bits per second) of any serial
 357 interface used by GDB for remote debugging.
 358
 359 .TP
 360 .BI "\-tty=" "device"\c
 361 \&
 362 Run using \c
 363 .I device\c
 364 \& for your program's standard input and output.
 365 .PP
 366
 367 .SH "SEE ALSO"
 368 .RB "`\|" gdb "\|'"
 369 entry in
 370 .B info\c
 371 \&;
 372 .I
 373 Using GDB: A Guide to the GNU Source-Level Debugger\c
 374 , Richard M. Stallman and Roland H. Pesch, July 1991.
 375 .SH COPYING
 376 Copyright (c) 1991, 2010 Free Software Foundation, Inc.
 377 .PP
 378 Permission is granted to make and distribute verbatim copies of
 379 this manual provided the copyright notice and this permission notice
 380 are preserved on all copies.
 381 .PP
 382 Permission is granted to copy and distribute modified versions of this
 383 manual under the conditions for verbatim copying, provided that the
 384 entire resulting derived work is distributed under the terms of a
 385 permission notice identical to this one.
 386 .PP
 387 Permission is granted to copy and distribute translations of this
 388 manual into another language, under the above conditions for modified
 389 versions, except that this permission notice may be included in
 390 translations approved by the Free Software Foundation instead of in
 391 the original English.