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