1 %%%%%%%%%%%%%%%% gdb-refcard.tex %%%%%%%%%%%%%%%%
3 %This file is TeX source for a reference card describing GDB, the GNU debugger.
5 %Copyright (C) 1991 Free Software Foundation, Inc.
6 %Permission is granted to make and distribute verbatim copies of
7 %this reference provided the copyright notices and permission notices
8 %are preserved on all copies.
10 %TeX markup is a programming language; accordingly this file is source
11 %for a program to generate a reference.
13 %This program is free software; you can redistribute it and/or modify
14 %it under the terms of the GNU General Public License as published by
15 %the Free Software Foundation; either version 1, or (at your option)
18 %This program is distributed in the hope that it will be useful, but
19 %WITHOUT ANY WARRANTY; without even the implied warranty of
20 %MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 %General Public License for more details.
23 %You can find a copy of the GNU General Public License in the GDB
24 %manual; or write to the Free Software Foundation, Inc.,
25 %675 Mass Ave, Cambridge, MA 02139, USA.
27 %You can contact the author as: pesch@cygnus.com
32 % Palo Alto, CA 94301 USA
36 % Uncomment the following `magnification' command if you want to print
37 % out in a larger font. Caution! You may need larger paper. You had
38 % best avoid using 3-column output if you try this. See the ``Three
39 % column format'' section below if you want to print in three column
42 %\magnification=\magstep 1
44 % NOTE ON INTENTIONAL OMISSIONS: This reference card includes most GDB
45 % commands, but due to space constraints there are some things I chose
46 % to omit. In general, not all synonyms for commands are covered, nor
47 % all variations of a command.
48 % The GDB-under-Emacs section omits gdb-mode functions without default
49 % keybindings. GDB startup options are not described.
50 % set print sevenbit-strings, set symbol-reloading omitted.
51 % printsyms, printpsyms, omitted since they're for GDB maintenance primarily
52 % share omitted due to obsolescence
53 % set check range/type omitted at least til code is in GDB.
56 \def\$
#1$
{{#1}}% Kluge: collect RCS revision info without $...$
57 \xdef\manvers{\$Revision$
}%
59 %-------------------- Three column format -----------------------
61 %%%% --- To disable three column format, comment out this entire section
63 % Three-column format for landscape printing on 8.5x11 paper
65 % We want output .25 inch *from paper edge*; i.e. -.75in from TeX default
66 \hoffset=-
0.8in
\voffset=-
0.75in
68 \fullhsize=
10.5in
\hsize=
3.3in
69 \def\fulline{\hbox to
\fullhsize}
70 \let\lcr=L
\newbox\leftcolumn\newbox\centercolumn
72 \global\setbox\leftcolumn=
\columnbox \global\let\lcr=C
75 \global\setbox\centercolumn=
\columnbox \global\let\lcr=R
76 \else \tripleformat \global\let\lcr=L
79 % \ifnum\outputpenalty>-20000 \else\dosupereject\fi
82 %ALTERNATIVE FOLDING GUIDES:
84 %For NO printed folding guide, comment out other \def\vdecor's and uncomment:
85 %\def\vdecor{\hskip .2in plus1fil}
87 %For SOLID LINE folding guide, comment out other \def\vdecor's and uncomment:
88 %\def\vdecor{\hskip .1in plus1fil \vrule width .1pt \hskip .1in plus1fil}
90 %For SMALL MARKS NEAR TOP AND BOTTOM as folding guide,
91 %comment out other \def\vdecor's and uncomment:
92 \def\vdecor{\hskip .1in plus1fil
93 \vbox to
\vsize{\hbox to
.1pt
{\vrule height
2pt width
.1pt
}\vfill
94 \hbox to
.1pt
{\vrule height
2pt width
.1pt
}}
97 %END OF ALTERNATIVES FOR FOLDING GUIDES
99 \def\tripleformat{\shipout\vbox{\fulline{\box\leftcolumn\vdecor
100 \box\centercolumn\vdecor
104 \def\columnbox{\leftline{\pagebody}}
107 \if R
\lcr \null\vfill\eject\fi
110 %-------------------- end three column format -----------------------
112 %-------------------- Computer Modern font defs: --------------------
120 %-------------------- end font defs ---------------------------------
124 \hyphenpenalty=
5000\tolerance=
2000\raggedright\raggedbottom
125 \normalbaselineskip=
9pt
\baselineskip=
9pt
129 \footline=
{\vbox to0pt
{\hss}}
131 \def\ctl#1{{\tt C-
#1}}
132 \def\opt#1{{\brm[{\rm #1}]}}
133 \def\xtra#1{\noalign{\smallskip{\tt#1}}}
135 \long\def\sec#1;
#2\endsec{\vskip 1pc
138 \vtop{\hsize=
1.1in
\tt
139 ##
\par\vskip 2pt
}\hfil
141 &
\vtop{\hsize=
2.1in
\hangafter=
1\hangindent=
0.5em
142 \rm ##
\par\vskip 2pt
}\cr
143 %Tail of \long\def fills in halign body with \sec args:
144 \noalign{{\bbf #1}\vskip 2pt
}
149 {\vbbf GDB QUICK REFERENCE
}\hfil{\smrm GDB Version
4}\qquad
151 \sec Essential Commands;
152 gdb
{\it program
} \opt{{\it core
}}&debug
{\it program
} \opt{using
153 coredump
{\it core
}}\cr
154 b
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it function
} \opt{in
\it file
}\cr
155 run
\opt{{\it arglist
}}&start your program
\opt{with
{\it arglist
}}\cr
156 bt& backtrace: display program stack
\cr
157 p
{\it expr
}&display the value of an expression
\cr
158 c &continue running your program
\cr
159 n &next line, stepping over function calls
\cr
160 s &next line, stepping into function calls
\cr
164 gdb&start GDB, with no debugging files
\cr
165 gdb
{\it program
}&begin debugging
{\it program
}\cr
166 gdb
{\it program core
}&debug coredump
{\it core
} produced by
{\it
168 gdb --help&describe command line options
\cr
172 quit&exit GDB; also
{\tt q
} or
{\tt EOF
} (eg
\ctl{d
})
\cr
173 INTERRUPT&(eg
\ctl{c
}) terminate current command, or send to running process
\cr
177 help&list classes of commands
\cr
178 help
{\it class
}&one-line descriptions for commands in
{\it class
}\cr
179 help
{\it command
}&describe
{\it command
}\cr
182 \sec Executing your Program;
183 run
{\it arglist
}&start your program with
{\it arglist
}\cr
184 run&start your program with current argument list
\cr
185 run $
\ldots$ <
{\it inf
} >
{\it outf
}&start your program with input, output
188 kill&kill running program
\cr
190 tty
{\it dev
}&use
{\it dev
} as stdin and stdout for next
{\tt run
}\cr
191 set args
{\it arglist
}&specify
{\it arglist
} for next
193 set args&specify empty argument list
\cr
194 show args&display argument list
\cr
196 show environment&show all environment variables
\cr
197 show env
{\it var
}&show value of environment variable
{\it var
}\cr
198 set env
{\it var
} {\it string
}&set environment variable
{\it var
}\cr
199 unset env
{\it var
}&remove
{\it var
} from environment
\cr
203 cd
{\it dir
}&change working directory to
{\it dir
}\cr
204 pwd&Print working directory
\cr
205 make $
\ldots$&call ``
{\tt make
}''
\cr
206 shell
{\it cmd
}&execute arbitrary shell command string
\cr
210 \line{\smrm \opt{ } surround optional arguments
\hfill $
\ldots$ show
211 one or more arguments
}
213 \centerline{\smrm \copyright 1991,
1992 Free Software Foundation, Inc.
\qquad Permissions on back
}
215 \sec Breakpoints and Watchpoints;
216 break
\opt{\it file
\tt:
}{\it line
}\par
217 b
\opt{\it file
\tt:
}{\it line
}&set breakpoint at
{\it line
} number
\opt{in
\it file
}\par
218 eg:
\quad{\tt break main.c:
37}\quad\cr
219 break
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it
220 function
} \opt{in
\it file
}\cr
221 break +
{\it offset
}\par
222 break -
{\it offset
}&set break at
{\it offset
} lines from current stop
\cr
223 break *
{\it addr
}&set breakpoint at address
{\it addr
}\cr
224 break&set breakpoint at next instruction
\cr
225 break $
\ldots$ if
{\it expr
}&break conditionally on nonzero
{\it expr
}\cr
226 cond
{\it n
} \opt{\it expr
}&new conditional expression on breakpoint
227 {\it n
}; make unconditional if no
{\it expr
}\cr
228 tbreak $
\ldots$&temporary break; disable when reached
\cr
229 rbreak
{\it regex
}&break on all functions matching
{\it regex
}\cr
230 watch
{\it expr
}&set a watchpoint for expression
{\it expr
}\cr
231 catch
{\it x
}&break at C++ handler for exception
{\it x
}\cr
233 info break&show defined breakpoints
\cr
234 info watch&show defined watchpoints
\cr
236 clear&delete breakpoints at next instruction
\cr
237 clear
\opt{\it file
\tt:
}{\it fun
}&delete breakpoints at entry to
{\it fun
}()
\cr
238 clear
\opt{\it file
\tt:
}{\it line
}&delete breakpoints on source line
\cr
239 delete
\opt{{\it n
}}&delete breakpoints
240 \opt{or breakpoint
{\it n
}}\cr
242 disable
\opt{{\it n
}}&disable breakpoints
243 \opt{or breakpoint
{\it n
}}
245 enable
\opt{{\it n
}}&enable breakpoints
246 \opt{or breakpoint
{\it n
}}
248 enable once
\opt{{\it n
}}&enable breakpoints
\opt{or breakpoint
{\it n
}};
249 disable again when reached
251 enable del
\opt{{\it n
}}&enable breakpoints
\opt{or breakpoint
{\it n
}};
255 ignore
{\it n
} {\it count
}&ignore breakpoint
{\it n
},
{\it count
}
259 \qquad \opt{\tt silent
}\par
260 \qquad {\it command-list
}&execute GDB
{\it command-list
} every time breakpoint
{\it n
} is reached.
\opt{{\tt silent
} suppresses default
262 end&end of
{\it command-list
}\cr
266 backtrace
\opt{\it n
}\par
267 bt
\opt{\it n
}&print trace of all frames in stack; or of
{\it n
}
268 frames---innermost if
{\it n
}{\tt >
0}, outermost if
{\it n
}{\tt <
0}\cr
269 frame
\opt{\it n
}&select frame number
{\it n
} or frame at address
{\it
270 n
}; if no
{\it n
}, display current frame
\cr
271 up
{\it n
}&select frame
{\it n
} frames up
\cr
272 down
{\it n
}&select frame
{\it n
} frames down
\cr
273 info frame
\opt{\it addr
}&describe selected frame, or frame at
275 info args&arguments of selected frame
\cr
276 info locals&local variables of selected frame
\cr
277 info reg
\opt{\it rn
}\par
278 info all-reg
\opt{\it rn
}®ister values
\opt{for reg
{\it rn\/
}} in
279 selected frame;
{\tt all-reg
} includes floating point
\cr
280 info catch&exception handlers active in selected frame
\cr
284 \sec Execution Control;
285 continue
\opt{\it count
}\par
286 c
\opt{\it count
}&continue running; if
{\it count
} specified, ignore
287 this breakpoint next
{\it count
} times
\cr
289 step
\opt{\it count
}\par
290 s
\opt{\it count
}&execute until another line reached; repeat
{\it count
} times if
292 stepi
\opt{\it count
}\par
293 si
\opt{\it count
}&step by machine instructions rather than source
296 next
\opt{\it count
}\par
297 n
\opt{\it count
}&execute next line, including any function calls
\cr
298 nexti
\opt{\it count
}\par
299 ni
\opt{\it count
}&next machine instruction rather than source
302 until
\opt{\it location
}&run until next instruction (or
{\it
304 finish&run until selected stack frame returns
\cr
305 return
\opt{\it expr
}&pop selected stack frame without executing
306 \opt{setting return value
}\cr
307 signal
{\it num
}&resume execution with signal
{\it s
} (none if
{\tt 0})
\cr
309 jump *
{\it address
}&resume execution at specified
{\it line
} number or
311 set var=
{\it expr
}&evaluate
{\it expr
} without displaying it; use for
312 altering program variables
\cr
316 print
\opt{\tt/
{\it f
}\/
} \opt{\it expr
}\par
317 p
\opt{\tt/
{\it f
}\/
} \opt{\it expr
}&show value of
{\it expr
} \opt{or
318 last value
\tt \$
} according to format
{\it f
}:
\cr
319 \qquad x&hexadecimal
\cr
320 \qquad d&signed decimal
\cr
321 \qquad u&unsigned decimal
\cr
324 \qquad a&address, absolute and relative
\cr
325 \qquad c&character
\cr
326 \qquad f&floating point
\cr
327 call
\opt{\tt /
{\it f
}\/
} {\it expr
}&like
{\tt print
} but does not display
329 x
\opt{\tt/
{\it Nuf
}\/
} {\it expr
}&examine memory at address
{\it expr
};
330 optional format spec follows slash
\cr
331 \quad {\it N
}&count of how many units to display
\cr
332 \quad {\it u
}&unit size; one of
\cr
333 &
{\tt\qquad b
}\ individual bytes
\cr
334 &
{\tt\qquad h
}\ halfwords (two bytes)
\cr
335 &
{\tt\qquad w
}\ words (four bytes)
\cr
336 &
{\tt\qquad g
}\ giant words (eight bytes)
\cr
337 \quad {\it f
}&printing format. Any
{\tt print
} format, or
\cr
338 &
{\tt\qquad s
}\ null-terminated string
\cr
339 &
{\tt\qquad i
}\ machine instructions
\cr
340 disassem
\opt{\it addr
}&display memory as machine instructions
\cr
343 \sec Automatic Display;
344 display
\opt{\tt/
\it f\/
} {\it expr
}&show value of
{\it expr
} each time
345 program stops
\opt{according to format
{\it f
}\/
}\cr
346 display&display all enabled expressions on list
\cr
347 undisplay
{\it n
}&remove number(s)
{\it n
} from list of
348 automatically displayed expressions
\cr
349 disable disp
{\it n
}&disable display for expression(s) number
{\it
351 enable disp
{\it n
}&enable display for expression(s) number
{\it
353 info display&numbered list of display expressions
\cr
359 {\it expr
}&an expression in C, C++, or Modula-
2 (including function calls), or:
\cr
360 {\it addr\/
}@
{\it len
}&an array of
{\it len
} elements beginning at
{\it
362 {\it file
}::
{\it nm
}&a variable or function
{\it nm
} defined in
{\it
364 $
\tt\
{$
{\it type
}$
\tt\
}$
{\it addr
}&read memory at
{\it addr
} as specified
366 \$&most recent displayed value
\cr
367 \$
{\it n
}&
{\it n
}th displayed value
\cr
368 \$\$&displayed value previous to \$
\cr
369 \$\$
{\it n
}&
{\it n
}th displayed value back from \$
\cr
370 \$
\_&last address examined with
{\tt x
}\cr
371 \$
\_\_&value at address \$
\_\cr
372 \$
{\it var
}&convenience variable; assign any value
\cr
374 show values
\opt{{\it n
}}&show last
10 values
\opt{or surrounding
376 show convenience&display all convenience variables
\cr
380 info address
{\it s
}&show where symbol
{\it s
} is stored
\cr
381 info func
\opt{\it regex
}&show names, types of defined functions
382 (all, or matching
{\it regex
})
\cr
383 info var
\opt{\it regex
}&show names, types of global variables (all,
384 or matching
{\it regex
})
\cr
385 whatis
\opt{\it expr
}\par
386 ptype
\opt{\it expr
}&show data type of
{\it expr
} \opt{or
\tt \$
}
387 without evaluating;
{\tt ptype
} gives more detail
\cr
388 ptype
{\it type
}&describe type, struct, union, or enum
\cr
392 source
{\it script
}&read, execute GDB commands from file
{\it
396 \qquad {\it command-list
}&create new GDB command
{\it cmd
};
397 execute script defined by
{\it command-list
}\cr
398 end&end of
{\it command-list
}\cr
399 document {\it cmd
}\par
400 \qquad {\it help-text
}&create online documentation
401 for new GDB command
{\it cmd
}\cr
402 end&end of
{\it help-text
}\cr
406 handle
{\it signal
} {\it act
}&specify GDB actions for
{\it signal
}:
\cr
407 \quad print&announce signal
\cr
408 \quad noprint&be silent for signal
\cr
409 \quad stop&halt execution on signal
\cr
410 \quad nostop&do not halt execution
\cr
411 \quad pass&allow your program to handle signal
\cr
412 \quad nopass&do not allow your program to see signal
\cr
413 info signals&show table of signals, GDB action for each
\cr
416 \sec Debugging Targets;
417 target
{\it type
} {\it param
}&connect to target machine, process, or file
\cr
418 help target&display available targets
\cr
419 attach
{\it param
}&connect to another process
\cr
420 detach&release target from GDB control
\cr
424 \sec Controlling GDB;
425 set
{\it param
} {\it value
}&set one of GDB's internal parameters
\cr
426 show
{\it param
}&display current setting of parameter
\cr
427 \xtra{\rm Parameters understood by
{\tt set
} and
{\tt show
}:
}
428 \quad complaints
{\it limit
}&number of messages on unusual symbols
\cr
429 \quad confirm
{\it on/off
}&enable or disable cautionary queries
\cr
430 \quad editing
{\it on/off
}&control
{\tt readline
} command-line editing
\cr
431 \quad height
{\it lpp
}&number of lines before pause in display
\cr
432 \quad language
{\it lang
}&Language for GDB expressions (
{\tt auto
},
{\tt c
} or
434 \quad listsize
{\it n
}&number of lines shown by
{\tt list
}\cr
435 \quad prompt
{\it str
}&use
{\it str
} as GDB prompt
\cr
436 \quad radix
{\it base
}&octal, decimal, or hex number representation
\cr
437 \quad verbose
{\it on/off
}&control messages when loading
439 \quad width
{\it cpl
}&number of characters before line folded
\cr
440 \quad write
{\it on/off
}&Allow or forbid patching binary, core files
441 (when reopened with
{\tt exec
} or
{\tt core
})
443 \quad history $
\ldots$
\par
444 \quad h $
\ldots$&groups with the following options:
\cr
445 \quad h exp
{\it off/on
}&disable/enable
{\tt readline
} history expansion
\cr
446 \quad h file
{\it filename
}&file for recording GDB command history
\cr
447 \quad h size
{\it size
}&number of commands kept in history list
\cr
448 \quad h save
{\it off/on
}&control use of external file for
451 \quad print $
\ldots$
\par
452 \quad p $
\ldots$&groups with the following options:
\cr
453 \quad p address
{\it on/off
}&print memory addresses in stacks,
455 \quad p array
{\it off/on
}&compact or attractive format for
457 \quad p demangl
{\it on/off
}&source (demangled) or internal form for C++
459 \quad p asm-dem
{\it on/off
}&demangle C++ symbols in
460 machine-instruction output
\cr
461 \quad p elements
{\it limit
}&number of array elements to display
\cr
462 \quad p object
{\it on/off
}&print C++ derived types for objects
\cr
463 \quad p pretty
{\it off/on
}&struct display: compact or indented
\cr
464 \quad p union
{\it on/off
}&display of union members
\cr
465 \quad p vtbl
{\it off/on
}&display of C++ virtual function
468 show commands&show last
10 commands
\cr
469 show commands
{\it n
}&show
10 commands around number
{\it n
}\cr
470 show commands +&show next
10 commands
\cr
474 file
\opt{\it file
}&use
{\it file
} for both symbols and executable;
475 with no arg, discard both
\cr
476 core
\opt{\it file
}&read
{\it file
} as coredump; or discard
\cr
477 exec
\opt{\it file
}&use
{\it file
} as executable only; or discard
\cr
478 symbol
\opt{\it file
}&use symbol table from
{\it file
}; or discard
\cr
479 load
{\it file
}&dynamically link
{\it file\/
} and add its symbols
\cr
480 add-sym
{\it file
} {\it addr
}&read additional symbols from
{\it file
},
481 dynamically loaded at
{\it addr
}\cr
482 info files&display working files and targets in use
\cr
483 path
{\it dirs
}&add
{\it dirs
} to front of path searched for
484 executable and symbol files
\cr
485 show path&display executable and symbol file path
\cr
486 info share&list names of shared libraries currently loaded
\cr
491 dir
{\it names
}&add directory
{\it names
} to front of source path
\cr
492 dir&clear source path
\cr
493 show dir&show current source path
\cr
495 list&show next ten lines of source
\cr
496 list -&show previous ten lines
\cr
497 list
{\it lines
}&display source centered around
{\it lines
},
498 specified as one of:
\cr
499 \quad{\opt{\it file
\tt:
}\it num
}&line number
\opt{in named file
}\cr
500 \quad{\opt{\it file
\tt:
}\it function
}&beginning of function
\opt{in
502 \quad{\tt +
\it off
}&
{\it off
} lines after last printed
\cr
503 \quad{\tt -
\it off
}&
{\it off
} lines previous to last printed
\cr
504 \quad{\tt*
\it address
}&line containing
{\it address
}\cr
505 list
{\it f
},
{\it l
}&from line
{\it f
} to line
{\it l
}\cr
506 info line
{\it num
}&show starting, ending addresses of compiled code for
507 source line
{\it num
}\cr
508 info source&show name of current source file
\cr
509 info sources&list all source files in use
\cr
510 forw
{\it regex
}&search following source lines for
{\it regex
}\cr
511 rev
{\it regex
}&search preceding source lines for
{\it regex
}\cr
514 \sec GDB under GNU Emacs;
515 M-x gdb&run GDB under Emacs
\cr
516 \ctl{h
} m&describe GDB mode
\cr
517 M-s&step one line (
{\tt step
})
\cr
518 M-n&next line (
{\tt next
})
\cr
519 M-i&step one instruction (
{\tt stepi
})
\cr
520 \ctl{c
} \ctl{f
}&finish current stack frame (
{\tt finish
})
\cr
521 M-c&continue (
{\tt cont
})
\cr
522 M-u&up
{\it arg
} frames (
{\tt up
})
\cr
523 M-d&down
{\it arg
} frames (
{\tt down
})
\cr
524 \ctl{x
} \&© number from point, insert at end
\cr
525 \ctl{x
} SPC&(in source file) set break at point
\cr
529 show copying&Display GNU General Public License
\cr
530 show warranty&There is NO WARRANTY for GDB. Display full no-warranty
537 \centerline{Copyright
\copyright 1991,
1992 Free Software Foundation, Inc.
}
538 \centerline{Roland Pesch (pesch@cygnus.com), January
1992---
\manvers}
539 \centerline{The author assumes no responsibility for any errors on this card.
}
541 This card may be freely distributed under the terms of the GNU
542 General Public License.
544 \centerline{Please contribute to development of this card by
547 GDB itself is free software; you are welcome to distribute copies of
548 it under the terms of the GNU General Public License. There is
549 absolutely no warranty for GDB.