gdb/gdb.1

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