contrib/gdb-7/gdb/gdb.1

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