gnu/usr.bin/binutils/gdb/gdb.1

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