1 %This file is TeX source for a reference card describing GDB, the GNU debugger.
3 %Copyright (C) 1991 Free Software Foundation, Inc.
4 %Permission is granted to make and distribute verbatim copies of
5 %this reference provided the copyright notices and permission notices
6 %are preserved on all copies.
8 %TeX markup is a programming language; accordingly this file is source
9 %for a program to generate a reference.
11 %This program is free software; you can redistribute it and/or modify
12 %it under the terms of the GNU General Public License as published by
13 %the Free Software Foundation; either version 1, or (at your option)
16 %This program is distributed in the hope that it will be useful, but
17 %WITHOUT ANY WARRANTY; without even the implied warranty of
18 %MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 %General Public License for more details.
21 %You can find a copy of the GNU General Public License in the GDB
22 %manual; or write to the Free Software Foundation, Inc.,
23 %675 Mass Ave, Cambridge, MA 02139, USA.
25 %You can contact the author as: pesch@cygnus.com
30 % Palo Alto, CA 94301 USA
34 % Cygnus Support is an organization devoted to commercial
35 % support of free software. For general information
36 % contact ``info@cygnus.com''
38 % NOTE ON INTENTIONAL OMISSIONS: This reference card includes most GDB
39 % commands, but due to space constraints there are some things I chose
40 % to omit. In general, not all synonyms for commands are covered, nor
41 % all variations of a command.
42 % The GDB-under-Emacs section omits gdb-mode functions without default
43 % keybindings. GDB startup options are not described.
44 % set print sevenbit-strings, set symbol-reloading omitted.
45 % printsyms, printpsyms, omitted since they're for GDB maintenance primarily
46 % share omitted due to obsolescence
47 % set check range/type omitted at least til code is in GDB.
52 \def\$
#1$
{{#1}}% Kluge: collect RCS revision info without $...$
53 \xdef\manvers{\$Revision$
}%
59 \hyphenpenalty=
5000\tolerance=
2000\raggedright\raggedbottom
60 \normalbaselineskip=
9pt
\baselineskip=
9pt
64 \footline=
{\vbox to0pt
{\hss}}
66 \def\ctl#1{{\tt C-
#1}}
67 \def\opt#1{{\brm[{\rm #1}]}}
68 \def\xtra#1{\noalign{\smallskip{\tt#1}}}
70 \long\def\sec#1;
#2\endsec{\vskip 1pc
74 ##
\par\vskip 2pt
}\hfil
76 &
\vtop{\hsize=
2.1in
\hangafter=
1\hangindent=
0.5em
77 \rm ##
\par\vskip 2pt
}\cr
78 %Tail of \long\def fills in halign body with \sec args:
79 \noalign{{\bbf #1}\vskip 2pt
}
83 {\vbbf GDB QUICK REFERENCE
}\hfil{\smrm GDB Version
4}
86 \hskip .33in
\epsfbox{cyglogo.eps
}
90 \sec Essential Commands;
91 gdb
{\it program
} \opt{{\it core
}}&debug
{\it program
} \opt{using
92 coredump
{\it core
}}\cr
93 b
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it function
} \opt{in
\it file
}\cr
94 run
\opt{{\it arglist
}}&start your program
\opt{with
{\it arglist
}}\cr
95 bt& backtrace: display program stack
\cr
96 p
{\it expr
}&display the value of an expression
\cr
97 c &continue running your program
\cr
98 n &next line, stepping over function calls
\cr
99 s &next line, stepping into function calls
\cr
103 gdb&start GDB, with no debugging files
\cr
104 gdb
{\it program
}&begin debugging
{\it program
}\cr
105 gdb
{\it program core
}&debug coredump
{\it core
} produced by
{\it
107 gdb -help&describe command line options
\cr
111 quit&exit GDB; also
{\tt q
} or
{\tt EOF
} (eg
\ctl{d
})
\cr
112 INTERRUPT&(eg
\ctl{c
}) terminate current command, or send to running process
\cr
116 help&list classes of commands
\cr
117 help
{\it class
}&one-line descriptions for commands in
{\it class
}\cr
118 help
{\it command
}&describe
{\it command
}\cr
121 \sec Executing your Program;
122 run
{\it arglist
}&start your program with
{\it arglist
}\cr
123 run&start your program with current argument list
\cr
124 run $
\ldots$ <
{\it inf
} >
{\it outf
}&start your program with input, output
127 kill&kill running program
\cr
129 tty
{\it dev
}&use
{\it dev
} as stdin and stdout for next
{\tt run
}\cr
130 set args
{\it arglist
}&specify
{\it arglist
} for next
132 set args&specify empty argument list
\cr
133 show args&display argument list
\cr
135 show environment&show all environment variables
\cr
136 show env
{\it var
}&show value of environment variable
{\it var
}\cr
137 set env
{\it var
} {\it string
}&set environment variable
{\it var
}\cr
138 unset env
{\it var
}&remove
{\it var
} from environment
\cr
142 cd
{\it dir
}&change working directory to
{\it dir
}\cr
143 pwd&Print working directory
\cr
144 make $
\ldots$&call ``
{\tt make
}''
\cr
145 shell
{\it cmd
}&execute arbitrary shell command string
\cr
150 \sec Breakpoints and Watchpoints;
151 break
\opt{\it file
\tt:
}{\it line
}\par
152 b
\opt{\it file
\tt:
}{\it line
}&set breakpoint at
{\it line
} number
\opt{in
\it file
}\par
153 eg:
\quad{\tt break main.c:
37}\quad\cr
154 break
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it
155 function
} \opt{in
\it file
}\cr
156 break +
{\it offset
}\par
157 break -
{\it offset
}&set break at
{\it offset
} lines from current stop
\cr
158 break *
{\it addr
}&set breakpoint at address
{\it addr
}\cr
159 break&set breakpoint at next instruction
\cr
160 break $
\ldots$ if
{\it expr
}&break conditionally on nonzero
{\it expr
}\cr
161 cond
{\it n
} \opt{\it expr
}&new conditional expression on breakpoint
162 {\it n
}; make unconditional if no
{\it expr
}\cr
163 tbreak $
\ldots$&temporary break; disable when reached
\cr
164 rbreak
{\it regex
}&break on all functions matching
{\it regex
}\cr
165 watch
{\it expr
}&set a watchpoint for expression
{\it expr
}\cr
166 catch
{\it x
}&break at C++ handler for exception
{\it x
}\cr
168 info break&show defined breakpoints
\cr
169 info watch&show defined watchpoints
\cr
171 clear&delete breakpoints at next instruction
\cr
172 clear
\opt{\it file
\tt:
}{\it fun
}&delete breakpoints at entry to
{\it fun
}()
\cr
173 clear
\opt{\it file
\tt:
}{\it line
}&delete breakpoints on source line
\cr
174 delete
\opt{{\it n
}}&delete breakpoints
175 \opt{or breakpoint
{\it n
}}\cr
177 disable
\opt{{\it n
}}&disable breakpoints
178 \opt{or breakpoint
{\it n
}}
180 enable
\opt{{\it n
}}&enable breakpoints
181 \opt{or breakpoint
{\it n
}}
183 enable once
\opt{{\it n
}}&enable breakpoints
\opt{or breakpoint
{\it n
}};
184 disable again when reached
186 enable del
\opt{{\it n
}}&enable breakpoints
\opt{or breakpoint
{\it n
}};
190 ignore
{\it n
} {\it count
}&ignore breakpoint
{\it n
},
{\it count
}
194 \qquad \opt{\tt silent
}\par
195 \qquad {\it command-list
}&execute GDB
{\it command-list
} every time breakpoint
{\it n
} is reached.
\opt{{\tt silent
} suppresses default
197 end&end of
{\it command-list
}\cr
201 backtrace
\opt{\it n
}\par
202 bt
\opt{\it n
}&print trace of all frames in stack; or of
{\it n
}
203 frames---innermost if
{\it n
}{\tt >
0}, outermost if
{\it n
}{\tt <
0}\cr
204 frame
\opt{\it n
}&select frame number
{\it n
} or frame at address
{\it
205 n
}; if no
{\it n
}, display current frame
\cr
206 up
{\it n
}&select frame
{\it n
} frames up
\cr
207 down
{\it n
}&select frame
{\it n
} frames down
\cr
208 info frame
\opt{\it addr
}&describe selected frame, or frame at
210 info args&arguments of selected frame
\cr
211 info locals&local variables of selected frame
\cr
212 info reg
\opt{\it rn
}\par
213 info all-reg
\opt{\it rn
}®ister values
\opt{for reg
{\it rn\/
}} in
214 selected frame;
{\tt all-reg
} includes floating point
\cr
215 info catch&exception handlers active in selected frame
\cr
219 \line{\smrm \opt{ } surround optional arguments.
\hfil $
\ldots$ show
220 one or more arguments
}
222 \centerline{\smrm \copyright 1991,
1992 Free Software Foundation, Inc.
\qquad Permissions on back
}
224 \sec Execution Control;
225 continue
\opt{\it count
}\par
226 c
\opt{\it count
}&continue running; if
{\it count
} specified, ignore
227 this breakpoint next
{\it count
} times
\cr
229 step
\opt{\it count
}\par
230 s
\opt{\it count
}&execute until another line reached; repeat
{\it count
} times if
232 stepi
\opt{\it count
}\par
233 si
\opt{\it count
}&step by machine instructions rather than source
236 next
\opt{\it count
}\par
237 n
\opt{\it count
}&execute next line, including any function calls
\cr
238 nexti
\opt{\it count
}\par
239 ni
\opt{\it count
}&next machine instruction rather than source
242 until
\opt{\it location
}&run until next instruction (or
{\it
244 finish&run until selected stack frame returns
\cr
245 return
\opt{\it expr
}&pop selected stack frame without executing
246 \opt{setting return value
}\cr
247 signal
{\it num
}&resume execution with signal
{\it s
} (none if
{\tt 0})
\cr
249 jump *
{\it address
}&resume execution at specified
{\it line
} number or
251 set var=
{\it expr
}&evaluate
{\it expr
} without displaying it; use for
252 altering program variables
\cr
256 print
\opt{\tt/
{\it f
}\/
} \opt{\it expr
}\par
257 p
\opt{\tt/
{\it f
}\/
} \opt{\it expr
}&show value of
{\it expr
} \opt{or
258 last value
\tt \$
} according to format
{\it f
}:
\cr
259 \qquad x&hexadecimal
\cr
260 \qquad d&signed decimal
\cr
261 \qquad u&unsigned decimal
\cr
264 \qquad a&address, absolute and relative
\cr
265 \qquad c&character
\cr
266 \qquad f&floating point
\cr
267 call
\opt{\tt /
{\it f
}\/
} {\it expr
}&like
{\tt print
} but does not display
269 x
\opt{\tt/
{\it Nuf
}\/
} {\it expr
}&examine memory at address
{\it expr
};
270 optional format spec follows slash
\cr
271 \quad {\it N
}&count of how many units to display
\cr
272 \quad {\it u
}&unit size; one of
\cr
273 &
{\tt\qquad b
}\ individual bytes
\cr
274 &
{\tt\qquad h
}\ halfwords (two bytes)
\cr
275 &
{\tt\qquad w
}\ words (four bytes)
\cr
276 &
{\tt\qquad g
}\ giant words (eight bytes)
\cr
277 \quad {\it f
}&printing format. Any
{\tt print
} format, or
\cr
278 &
{\tt\qquad s
}\ null-terminated string
\cr
279 &
{\tt\qquad i
}\ machine instructions
\cr
280 disassem
\opt{\it addr
}&display memory as machine instructions
\cr
283 \sec Automatic Display;
284 display
\opt{\tt/
\it f\/
} {\it expr
}&show value of
{\it expr
} each time
285 program stops
\opt{according to format
{\it f
}\/
}\cr
286 display&display all enabled expressions on list
\cr
287 undisplay
{\it n
}&remove number(s)
{\it n
} from list of
288 automatically displayed expressions
\cr
289 disable disp
{\it n
}&disable display for expression(s) number
{\it
291 enable disp
{\it n
}&enable display for expression(s) number
{\it
293 info display&numbered list of display expressions
\cr
299 {\it expr
}&an expression in C, C++, or Modula-
2 (including function calls), or:
\cr
300 {\it addr\/
}@
{\it len
}&an array of
{\it len
} elements beginning at
{\it
302 {\it file
}::
{\it nm
}&a variable or function
{\it nm
} defined in
{\it
304 $
\tt\
{$
{\it type
}$
\tt\
}$
{\it addr
}&read memory at
{\it addr
} as specified
306 \$&most recent displayed value
\cr
307 \$
{\it n
}&
{\it n
}th displayed value
\cr
308 \$\$&displayed value previous to \$
\cr
309 \$\$
{\it n
}&
{\it n
}th displayed value back from \$
\cr
310 \$
\_&last address examined with
{\tt x
}\cr
311 \$
\_\_&value at address \$
\_\cr
312 \$
{\it var
}&convenience variable; assign any value
\cr
314 show values
\opt{{\it n
}}&show last
10 values
\opt{or surrounding
316 show convenience&display all convenience variables
\cr
320 info address
{\it s
}&show where symbol
{\it s
} is stored
\cr
321 info func
\opt{\it regex
}&show names, types of defined functions
322 (all, or matching
{\it regex
})
\cr
323 info var
\opt{\it regex
}&show names, types of global variables (all,
324 or matching
{\it regex
})
\cr
325 whatis
\opt{\it expr
}\par
326 ptype
\opt{\it expr
}&show data type of
{\it expr
} \opt{or
\tt \$
}
327 without evaluating;
{\tt ptype
} gives more detail
\cr
328 ptype
{\it type
}&describe type, struct, union, or enum
\cr
332 source
{\it script
}&read, execute GDB commands from file
{\it
336 \qquad {\it command-list
}&create new GDB command
{\it cmd
};
337 execute script defined by
{\it command-list
}\cr
338 end&end of
{\it command-list
}\cr
339 document {\it cmd
}\par
340 \qquad {\it help-text
}&create online documentation
341 for new GDB command
{\it cmd
}\cr
342 end&end of
{\it help-text
}\cr
346 handle
{\it signal
} {\it act
}&specify GDB actions for
{\it signal
}:
\cr
347 \quad print&announce signal
\cr
348 \quad noprint&be silent for signal
\cr
349 \quad stop&halt execution on signal
\cr
350 \quad nostop&do not halt execution
\cr
351 \quad pass&allow your program to handle signal
\cr
352 \quad nopass&do not allow your program to see signal
\cr
353 info signals&show table of signals, GDB action for each
\cr
356 \sec Debugging Targets;
357 target
{\it type
} {\it param
}&connect to target machine, process, or file
\cr
358 help target&display available targets
\cr
359 attach
{\it param
}&connect to another process
\cr
360 detach&release target from GDB control
\cr
364 \sec Controlling GDB;
365 set
{\it param
} {\it value
}&set one of GDB's internal parameters
\cr
366 show
{\it param
}&display current setting of parameter
\cr
367 \xtra{\rm Parameters understood by
{\tt set
} and
{\tt show
}:
}
368 \quad complaints
{\it limit
}&number of messages on unusual symbols
\cr
369 \quad confirm
{\it on/off
}&enable or disable cautionary queries
\cr
370 \quad editing
{\it on/off
}&control
{\tt readline
} command-line editing
\cr
371 \quad height
{\it lpp
}&number of lines before pause in display
\cr
372 \quad language
{\it lang
}&Language for GDB expressions (
{\tt auto
},
{\tt c
} or
374 \quad listsize
{\it n
}&number of lines shown by
{\tt list
}\cr
375 \quad prompt
{\it str
}&use
{\it str
} as GDB prompt
\cr
376 \quad radix
{\it base
}&octal, decimal, or hex number representation
\cr
377 \quad verbose
{\it on/off
}&control messages when loading
379 \quad width
{\it cpl
}&number of characters before line folded
\cr
380 \quad write
{\it on/off
}&Allow or forbid patching binary, core files
381 (when reopened with
{\tt exec
} or
{\tt core
})
383 \quad history $
\ldots$
\par
384 \quad h $
\ldots$&groups with the following options:
\cr
385 \quad h exp
{\it off/on
}&disable/enable
{\tt readline
} history expansion
\cr
386 \quad h file
{\it filename
}&file for recording GDB command history
\cr
387 \quad h size
{\it size
}&number of commands kept in history list
\cr
388 \quad h save
{\it off/on
}&control use of external file for
391 \quad print $
\ldots$
\par
392 \quad p $
\ldots$&groups with the following options:
\cr
393 \quad p address
{\it on/off
}&print memory addresses in stacks,
395 \quad p array
{\it off/on
}&compact or attractive format for
397 \quad p demangl
{\it on/off
}&source (demangled) or internal form for C++
399 \quad p asm-dem
{\it on/off
}&demangle C++ symbols in
400 machine-instruction output
\cr
401 \quad p elements
{\it limit
}&number of array elements to display
\cr
402 \quad p object
{\it on/off
}&print C++ derived types for objects
\cr
403 \quad p pretty
{\it off/on
}&struct display: compact or indented
\cr
404 \quad p union
{\it on/off
}&display of union members
\cr
405 \quad p vtbl
{\it off/on
}&display of C++ virtual function
408 show commands&show last
10 commands
\cr
409 show commands
{\it n
}&show
10 commands around number
{\it n
}\cr
410 show commands +&show next
10 commands
\cr
414 file
\opt{\it file
}&use
{\it file
} for both symbols and executable;
415 with no arg, discard both
\cr
416 core
\opt{\it file
}&read
{\it file
} as coredump; or discard
\cr
417 exec
\opt{\it file
}&use
{\it file
} as executable only; or discard
\cr
418 symbol
\opt{\it file
}&use symbol table from
{\it file
}; or discard
\cr
419 load
{\it file
}&dynamically link
{\it file\/
} and add its symbols
\cr
420 add-sym
{\it file
} {\it addr
}&read additional symbols from
{\it file
},
421 dynamically loaded at
{\it addr
}\cr
422 info files&display working files and targets in use
\cr
423 path
{\it dirs
}&add
{\it dirs
} to front of path searched for
424 executable and symbol files
\cr
425 show path&display executable and symbol file path
\cr
426 info share&list names of shared libraries currently loaded
\cr
431 dir
{\it names
}&add directory
{\it names
} to front of source path
\cr
432 dir&clear source path
\cr
433 show dir&show current source path
\cr
435 list&show next ten lines of source
\cr
436 list -&show previous ten lines
\cr
437 list
{\it lines
}&display source centered around
{\it lines
},
438 specified as one of:
\cr
439 \quad{\opt{\it file
\tt:
}\it num
}&line number
\opt{in named file
}\cr
440 \quad{\opt{\it file
\tt:
}\it function
}&beginning of function
\opt{in
442 \quad{\tt +
\it off
}&
{\it off
} lines after last printed
\cr
443 \quad{\tt -
\it off
}&
{\it off
} lines previous to last printed
\cr
444 \quad{\tt*
\it address
}&line containing
{\it address
}\cr
445 list
{\it f
},
{\it l
}&from line
{\it f
} to line
{\it l
}\cr
446 info line
{\it num
}&show starting, ending addresses of compiled code for
447 source line
{\it num
}\cr
448 info source&show name of current source file
\cr
449 info sources&list all source files in use
\cr
450 forw
{\it regex
}&search following source lines for
{\it regex
}\cr
451 rev
{\it regex
}&search preceding source lines for
{\it regex
}\cr
454 \sec GDB under GNU Emacs;
455 M-x gdb&run GDB under Emacs
\cr
456 \ctl{h
} m&describe GDB mode
\cr
457 M-s&step one line (
{\tt step
})
\cr
458 M-n&next line (
{\tt next
})
\cr
459 M-i&step one instruction (
{\tt stepi
})
\cr
460 \ctl{c
} \ctl{f
}&finish current stack frame (
{\tt finish
})
\cr
461 M-c&continue (
{\tt cont
})
\cr
462 M-u&up
{\it arg
} frames (
{\tt up
})
\cr
463 M-d&down
{\it arg
} frames (
{\tt down
})
\cr
464 \ctl{x
} \&© number from point, insert at end
\cr
465 \ctl{x
} SPC&(in source file) set break at point
\cr
469 show copying&Display GNU General Public License
\cr
470 show warranty&There is NO WARRANTY for GDB. Display full no-warranty
477 \centerline{Copyright
\copyright 1991,
1992 Free Software Foundation, Inc.
}
478 \centerline{Roland Pesch (pesch@cygnus.com), January
1992---
\manvers}
479 \centerline{The author assumes no responsibility for any errors on this card.
}
481 This card may be freely distributed under the terms of the GNU
482 General Public License.
484 \centerline{Please contribute to development of this card by
487 GDB itself is free software; you are welcome to distribute copies of
488 it under the terms of the GNU General Public License. There is
489 absolutely no warranty for GDB.