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$
}%
55 %-------------------- Three column format -----------------------
57 %%%% --- To disable three column format, comment out this entire section
59 % Three-column format for landscape printing on 8.5x11 paper
61 % We want output .25 inch *from paper edge*; i.e. -.75in from TeX default
62 \hoffset=-
0.8in
\voffset=-
0.75in
64 \fullhsize=
10.5in
\hsize=
3.3in
65 \def\fulline{\hbox to
\fullhsize}
66 \let\lcr=L
\newbox\leftcolumn\newbox\centercolumn
68 \global\setbox\leftcolumn=
\columnbox \global\let\lcr=C
71 \global\setbox\centercolumn=
\columnbox \global\let\lcr=R
72 \else \tripleformat \global\let\lcr=L
75 % \ifnum\outputpenalty>-20000 \else\dosupereject\fi
78 %ALTERNATIVE FOLDING GUIDES:
80 %For NO printed folding guide, comment out other \def\vdecor's and uncomment:
81 %\def\vdecor{\hskip .2in plus1fil}
83 %For SOLID LINE folding guide, comment out other \def\vdecor's and uncomment:
84 %\def\vdecor{\hskip .1in plus1fil \vrule width .1pt \hskip .1in plus1fil}
86 %For SMALL MARKS NEAR TOP AND BOTTOM as folding guide,
87 %comment out other \def\vdecor's and uncomment:
88 \def\vdecor{\hskip .1in plus1fil
89 \vbox to
\vsize{\hbox to
.1pt
{\vrule height
2pt width
.1pt
}\vfill
90 \hbox to
.1pt
{\vrule height
2pt width
.1pt
}}
93 %END OF ALTERNATIVES FOR FOLDING GUIDES
95 \def\tripleformat{\shipout\vbox{\fulline{\box\leftcolumn\vdecor
96 \box\centercolumn\vdecor
100 \def\columnbox{\leftline{\pagebody}}
103 \if R
\lcr \null\vfill\eject\fi
106 %-------------------- end three column format -----------------------
108 %-------------------- PostScript (K Berry names) font defs: --------------
109 \font\bbf=ptmb at
10pt
110 \font\vbbf=ptmb at
12pt
111 \font\smrm=ptmr at
6pt
112 \font\brm=ptmr at
10pt
114 \font\it=ptmri at
8pt
116 % Used only for copyright, replacing plain TeX macro.
117 \font\sym=psyr at
7pt
118 \def\copyright{{\sym\char'
323}}
119 %-------------------- end font defs ---------------------------------
123 \hyphenpenalty=
5000\tolerance=
2000\raggedright\raggedbottom
124 \normalbaselineskip=
9pt
\baselineskip=
9pt
128 \footline=
{\vbox to0pt
{\hss}}
130 \def\ctl#1{{\tt C-
#1}}
131 \def\opt#1{{\brm[{\rm #1}]}}
132 \def\xtra#1{\noalign{\smallskip{\tt#1}}}
134 \long\def\sec#1;
#2\endsec{\vskip 1pc
137 \vtop{\hsize=
1.1in
\tt
138 ##
\par\vskip 2pt
}\hfil
140 &
\vtop{\hsize=
2.1in
\hangafter=
1\hangindent=
0.5em
141 \rm ##
\par\vskip 2pt
}\cr
142 %Tail of \long\def fills in halign body with \sec args:
143 \noalign{{\bbf #1}\vskip 2pt
}
147 {\vbbf GDB QUICK REFERENCE
}\hfil{\smrm GDB Version
4}
150 \hskip .33in
\epsfbox{cyglogo.eps
}
154 \sec Essential Commands;
155 gdb
{\it program
} \opt{{\it core
}}&debug
{\it program
} \opt{using
156 coredump
{\it core
}}\cr
157 b
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it function
} \opt{in
\it file
}\cr
158 run
\opt{{\it arglist
}}&start your program
\opt{with
{\it arglist
}}\cr
159 bt& backtrace: display program stack
\cr
160 p
{\it expr
}&display the value of an expression
\cr
161 c &continue running your program
\cr
162 n &next line, stepping over function calls
\cr
163 s &next line, stepping into function calls
\cr
167 gdb&start GDB, with no debugging files
\cr
168 gdb
{\it program
}&begin debugging
{\it program
}\cr
169 gdb
{\it program core
}&debug coredump
{\it core
} produced by
{\it
171 gdb --help&describe command line options
\cr
175 quit&exit GDB; also
{\tt q
} or
{\tt EOF
} (eg
\ctl{d
})
\cr
176 INTERRUPT&(eg
\ctl{c
}) terminate current command, or send to running process
\cr
180 help&list classes of commands
\cr
181 help
{\it class
}&one-line descriptions for commands in
{\it class
}\cr
182 help
{\it command
}&describe
{\it command
}\cr
185 \sec Executing your Program;
186 run
{\it arglist
}&start your program with
{\it arglist
}\cr
187 run&start your program with current argument list
\cr
188 run $
\ldots$ <
{\it inf
} >
{\it outf
}&start your program with input, output
191 kill&kill running program
\cr
193 tty
{\it dev
}&use
{\it dev
} as stdin and stdout for next
{\tt run
}\cr
194 set args
{\it arglist
}&specify
{\it arglist
} for next
196 set args&specify empty argument list
\cr
197 show args&display argument list
\cr
199 show environment&show all environment variables
\cr
200 show env
{\it var
}&show value of environment variable
{\it var
}\cr
201 set env
{\it var
} {\it string
}&set environment variable
{\it var
}\cr
202 unset env
{\it var
}&remove
{\it var
} from environment
\cr
206 cd
{\it dir
}&change working directory to
{\it dir
}\cr
207 pwd&Print working directory
\cr
208 make $
\ldots$&call ``
{\tt make
}''
\cr
209 shell
{\it cmd
}&execute arbitrary shell command string
\cr
214 \sec Breakpoints and Watchpoints;
215 break
\opt{\it file
\tt:
}{\it line
}\par
216 b
\opt{\it file
\tt:
}{\it line
}&set breakpoint at
{\it line
} number
\opt{in
\it file
}\par
217 eg:
\quad{\tt break main.c:
37}\quad\cr
218 break
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it
219 function
} \opt{in
\it file
}\cr
220 break +
{\it offset
}\par
221 break -
{\it offset
}&set break at
{\it offset
} lines from current stop
\cr
222 break *
{\it addr
}&set breakpoint at address
{\it addr
}\cr
223 break&set breakpoint at next instruction
\cr
224 break $
\ldots$ if
{\it expr
}&break conditionally on nonzero
{\it expr
}\cr
225 cond
{\it n
} \opt{\it expr
}&new conditional expression on breakpoint
226 {\it n
}; make unconditional if no
{\it expr
}\cr
227 tbreak $
\ldots$&temporary break; disable when reached
\cr
228 rbreak
{\it regex
}&break on all functions matching
{\it regex
}\cr
229 watch
{\it expr
}&set a watchpoint for expression
{\it expr
}\cr
230 catch
{\it x
}&break at C++ handler for exception
{\it x
}\cr
232 info break&show defined breakpoints
\cr
233 info watch&show defined watchpoints
\cr
235 clear&delete breakpoints at next instruction
\cr
236 clear
\opt{\it file
\tt:
}{\it fun
}&delete breakpoints at entry to
{\it fun
}()
\cr
237 clear
\opt{\it file
\tt:
}{\it line
}&delete breakpoints on source line
\cr
238 delete
\opt{{\it n
}}&delete breakpoints
239 \opt{or breakpoint
{\it n
}}\cr
241 disable
\opt{{\it n
}}&disable breakpoints
242 \opt{or breakpoint
{\it n
}}
244 enable
\opt{{\it n
}}&enable breakpoints
245 \opt{or breakpoint
{\it n
}}
247 enable once
\opt{{\it n
}}&enable breakpoints
\opt{or breakpoint
{\it n
}};
248 disable again when reached
250 enable del
\opt{{\it n
}}&enable breakpoints
\opt{or breakpoint
{\it n
}};
254 ignore
{\it n
} {\it count
}&ignore breakpoint
{\it n
},
{\it count
}
258 \qquad \opt{\tt silent
}\par
259 \qquad {\it command-list
}&execute GDB
{\it command-list
} every time breakpoint
{\it n
} is reached.
\opt{{\tt silent
} suppresses default
261 end&end of
{\it command-list
}\cr
265 backtrace
\opt{\it n
}\par
266 bt
\opt{\it n
}&print trace of all frames in stack; or of
{\it n
}
267 frames---innermost if
{\it n
}{\tt >
0}, outermost if
{\it n
}{\tt <
0}\cr
268 frame
\opt{\it n
}&select frame number
{\it n
} or frame at address
{\it
269 n
}; if no
{\it n
}, display current frame
\cr
270 up
{\it n
}&select frame
{\it n
} frames up
\cr
271 down
{\it n
}&select frame
{\it n
} frames down
\cr
272 info frame
\opt{\it addr
}&describe selected frame, or frame at
274 info args&arguments of selected frame
\cr
275 info locals&local variables of selected frame
\cr
276 info reg
\opt{\it rn
}\par
277 info all-reg
\opt{\it rn
}®ister values
\opt{for reg
{\it rn\/
}} in
278 selected frame;
{\tt all-reg
} includes floating point
\cr
279 info catch&exception handlers active in selected frame
\cr
283 \line{\smrm \opt{ } surround optional arguments.
\hfil $
\ldots$ show
284 one or more arguments
}
286 \centerline{\smrm \copyright 1991,
1992 Free Software Foundation, Inc.
\qquad Permissions on back
}
288 \sec Execution Control;
289 continue
\opt{\it count
}\par
290 c
\opt{\it count
}&continue running; if
{\it count
} specified, ignore
291 this breakpoint next
{\it count
} times
\cr
293 step
\opt{\it count
}\par
294 s
\opt{\it count
}&execute until another line reached; repeat
{\it count
} times if
296 stepi
\opt{\it count
}\par
297 si
\opt{\it count
}&step by machine instructions rather than source
300 next
\opt{\it count
}\par
301 n
\opt{\it count
}&execute next line, including any function calls
\cr
302 nexti
\opt{\it count
}\par
303 ni
\opt{\it count
}&next machine instruction rather than source
306 until
\opt{\it location
}&run until next instruction (or
{\it
308 finish&run until selected stack frame returns
\cr
309 return
\opt{\it expr
}&pop selected stack frame without executing
310 \opt{setting return value
}\cr
311 signal
{\it num
}&resume execution with signal
{\it s
} (none if
{\tt 0})
\cr
313 jump *
{\it address
}&resume execution at specified
{\it line
} number or
315 set var=
{\it expr
}&evaluate
{\it expr
} without displaying it; use for
316 altering program variables
\cr
320 print
\opt{\tt/
{\it f
}\/
} \opt{\it expr
}\par
321 p
\opt{\tt/
{\it f
}\/
} \opt{\it expr
}&show value of
{\it expr
} \opt{or
322 last value
\tt \$
} according to format
{\it f
}:
\cr
323 \qquad x&hexadecimal
\cr
324 \qquad d&signed decimal
\cr
325 \qquad u&unsigned decimal
\cr
328 \qquad a&address, absolute and relative
\cr
329 \qquad c&character
\cr
330 \qquad f&floating point
\cr
331 call
\opt{\tt /
{\it f
}\/
} {\it expr
}&like
{\tt print
} but does not display
333 x
\opt{\tt/
{\it Nuf
}\/
} {\it expr
}&examine memory at address
{\it expr
};
334 optional format spec follows slash
\cr
335 \quad {\it N
}&count of how many units to display
\cr
336 \quad {\it u
}&unit size; one of
\cr
337 &
{\tt\qquad b
}\ individual bytes
\cr
338 &
{\tt\qquad h
}\ halfwords (two bytes)
\cr
339 &
{\tt\qquad w
}\ words (four bytes)
\cr
340 &
{\tt\qquad g
}\ giant words (eight bytes)
\cr
341 \quad {\it f
}&printing format. Any
{\tt print
} format, or
\cr
342 &
{\tt\qquad s
}\ null-terminated string
\cr
343 &
{\tt\qquad i
}\ machine instructions
\cr
344 disassem
\opt{\it addr
}&display memory as machine instructions
\cr
347 \sec Automatic Display;
348 display
\opt{\tt/
\it f\/
} {\it expr
}&show value of
{\it expr
} each time
349 program stops
\opt{according to format
{\it f
}\/
}\cr
350 display&display all enabled expressions on list
\cr
351 undisplay
{\it n
}&remove number(s)
{\it n
} from list of
352 automatically displayed expressions
\cr
353 disable disp
{\it n
}&disable display for expression(s) number
{\it
355 enable disp
{\it n
}&enable display for expression(s) number
{\it
357 info display&numbered list of display expressions
\cr
363 {\it expr
}&an expression in C, C++, or Modula-
2 (including function calls), or:
\cr
364 {\it addr\/
}@
{\it len
}&an array of
{\it len
} elements beginning at
{\it
366 {\it file
}::
{\it nm
}&a variable or function
{\it nm
} defined in
{\it
368 $
\tt\
{$
{\it type
}$
\tt\
}$
{\it addr
}&read memory at
{\it addr
} as specified
370 \$&most recent displayed value
\cr
371 \$
{\it n
}&
{\it n
}th displayed value
\cr
372 \$\$&displayed value previous to \$
\cr
373 \$\$
{\it n
}&
{\it n
}th displayed value back from \$
\cr
374 \$
\_&last address examined with
{\tt x
}\cr
375 \$
\_\_&value at address \$
\_\cr
376 \$
{\it var
}&convenience variable; assign any value
\cr
378 show values
\opt{{\it n
}}&show last
10 values
\opt{or surrounding
380 show convenience&display all convenience variables
\cr
384 info address
{\it s
}&show where symbol
{\it s
} is stored
\cr
385 info func
\opt{\it regex
}&show names, types of defined functions
386 (all, or matching
{\it regex
})
\cr
387 info var
\opt{\it regex
}&show names, types of global variables (all,
388 or matching
{\it regex
})
\cr
389 whatis
\opt{\it expr
}\par
390 ptype
\opt{\it expr
}&show data type of
{\it expr
} \opt{or
\tt \$
}
391 without evaluating;
{\tt ptype
} gives more detail
\cr
392 ptype
{\it type
}&describe type, struct, union, or enum
\cr
396 source
{\it script
}&read, execute GDB commands from file
{\it
400 \qquad {\it command-list
}&create new GDB command
{\it cmd
};
401 execute script defined by
{\it command-list
}\cr
402 end&end of
{\it command-list
}\cr
403 document {\it cmd
}\par
404 \qquad {\it help-text
}&create online documentation
405 for new GDB command
{\it cmd
}\cr
406 end&end of
{\it help-text
}\cr
410 handle
{\it signal
} {\it act
}&specify GDB actions for
{\it signal
}:
\cr
411 \quad print&announce signal
\cr
412 \quad noprint&be silent for signal
\cr
413 \quad stop&halt execution on signal
\cr
414 \quad nostop&do not halt execution
\cr
415 \quad pass&allow your program to handle signal
\cr
416 \quad nopass&do not allow your program to see signal
\cr
417 info signals&show table of signals, GDB action for each
\cr
420 \sec Debugging Targets;
421 target
{\it type
} {\it param
}&connect to target machine, process, or file
\cr
422 help target&display available targets
\cr
423 attach
{\it param
}&connect to another process
\cr
424 detach&release target from GDB control
\cr
428 \sec Controlling GDB;
429 set
{\it param
} {\it value
}&set one of GDB's internal parameters
\cr
430 show
{\it param
}&display current setting of parameter
\cr
431 \xtra{\rm Parameters understood by
{\tt set
} and
{\tt show
}:
}
432 \quad complaints
{\it limit
}&number of messages on unusual symbols
\cr
433 \quad confirm
{\it on/off
}&enable or disable cautionary queries
\cr
434 \quad editing
{\it on/off
}&control
{\tt readline
} command-line editing
\cr
435 \quad height
{\it lpp
}&number of lines before pause in display
\cr
436 \quad language
{\it lang
}&Language for GDB expressions (
{\tt auto
},
{\tt c
} or
438 \quad listsize
{\it n
}&number of lines shown by
{\tt list
}\cr
439 \quad prompt
{\it str
}&use
{\it str
} as GDB prompt
\cr
440 \quad radix
{\it base
}&octal, decimal, or hex number representation
\cr
441 \quad verbose
{\it on/off
}&control messages when loading
443 \quad width
{\it cpl
}&number of characters before line folded
\cr
444 \quad write
{\it on/off
}&Allow or forbid patching binary, core files
445 (when reopened with
{\tt exec
} or
{\tt core
})
447 \quad history $
\ldots$
\par
448 \quad h $
\ldots$&groups with the following options:
\cr
449 \quad h exp
{\it off/on
}&disable/enable
{\tt readline
} history expansion
\cr
450 \quad h file
{\it filename
}&file for recording GDB command history
\cr
451 \quad h size
{\it size
}&number of commands kept in history list
\cr
452 \quad h save
{\it off/on
}&control use of external file for
455 \quad print $
\ldots$
\par
456 \quad p $
\ldots$&groups with the following options:
\cr
457 \quad p address
{\it on/off
}&print memory addresses in stacks,
459 \quad p array
{\it off/on
}&compact or attractive format for
461 \quad p demangl
{\it on/off
}&source (demangled) or internal form for C++
463 \quad p asm-dem
{\it on/off
}&demangle C++ symbols in
464 machine-instruction output
\cr
465 \quad p elements
{\it limit
}&number of array elements to display
\cr
466 \quad p object
{\it on/off
}&print C++ derived types for objects
\cr
467 \quad p pretty
{\it off/on
}&struct display: compact or indented
\cr
468 \quad p union
{\it on/off
}&display of union members
\cr
469 \quad p vtbl
{\it off/on
}&display of C++ virtual function
472 show commands&show last
10 commands
\cr
473 show commands
{\it n
}&show
10 commands around number
{\it n
}\cr
474 show commands +&show next
10 commands
\cr
478 file
\opt{\it file
}&use
{\it file
} for both symbols and executable;
479 with no arg, discard both
\cr
480 core
\opt{\it file
}&read
{\it file
} as coredump; or discard
\cr
481 exec
\opt{\it file
}&use
{\it file
} as executable only; or discard
\cr
482 symbol
\opt{\it file
}&use symbol table from
{\it file
}; or discard
\cr
483 load
{\it file
}&dynamically link
{\it file\/
} and add its symbols
\cr
484 add-sym
{\it file
} {\it addr
}&read additional symbols from
{\it file
},
485 dynamically loaded at
{\it addr
}\cr
486 info files&display working files and targets in use
\cr
487 path
{\it dirs
}&add
{\it dirs
} to front of path searched for
488 executable and symbol files
\cr
489 show path&display executable and symbol file path
\cr
490 info share&list names of shared libraries currently loaded
\cr
495 dir
{\it names
}&add directory
{\it names
} to front of source path
\cr
496 dir&clear source path
\cr
497 show dir&show current source path
\cr
499 list&show next ten lines of source
\cr
500 list -&show previous ten lines
\cr
501 list
{\it lines
}&display source centered around
{\it lines
},
502 specified as one of:
\cr
503 \quad{\opt{\it file
\tt:
}\it num
}&line number
\opt{in named file
}\cr
504 \quad{\opt{\it file
\tt:
}\it function
}&beginning of function
\opt{in
506 \quad{\tt +
\it off
}&
{\it off
} lines after last printed
\cr
507 \quad{\tt -
\it off
}&
{\it off
} lines previous to last printed
\cr
508 \quad{\tt*
\it address
}&line containing
{\it address
}\cr
509 list
{\it f
},
{\it l
}&from line
{\it f
} to line
{\it l
}\cr
510 info line
{\it num
}&show starting, ending addresses of compiled code for
511 source line
{\it num
}\cr
512 info source&show name of current source file
\cr
513 info sources&list all source files in use
\cr
514 forw
{\it regex
}&search following source lines for
{\it regex
}\cr
515 rev
{\it regex
}&search preceding source lines for
{\it regex
}\cr
518 \sec GDB under GNU Emacs;
519 M-x gdb&run GDB under Emacs
\cr
520 \ctl{h
} m&describe GDB mode
\cr
521 M-s&step one line (
{\tt step
})
\cr
522 M-n&next line (
{\tt next
})
\cr
523 M-i&step one instruction (
{\tt stepi
})
\cr
524 \ctl{c
} \ctl{f
}&finish current stack frame (
{\tt finish
})
\cr
525 M-c&continue (
{\tt cont
})
\cr
526 M-u&up
{\it arg
} frames (
{\tt up
})
\cr
527 M-d&down
{\it arg
} frames (
{\tt down
})
\cr
528 \ctl{x
} \&© number from point, insert at end
\cr
529 \ctl{x
} SPC&(in source file) set break at point
\cr
533 show copying&Display GNU General Public License
\cr
534 show warranty&There is NO WARRANTY for GDB. Display full no-warranty
541 \centerline{Copyright
\copyright 1991,
1992 Free Software Foundation, Inc.
}
542 \centerline{Roland Pesch (pesch@cygnus.com), January
1992---
\manvers}
543 \centerline{The author assumes no responsibility for any errors on this card.
}
545 This card may be freely distributed under the terms of the GNU
546 General Public License.
548 \centerline{Please contribute to development of this card by
551 GDB itself is free software; you are welcome to distribute copies of
552 it under the terms of the GNU General Public License. There is
553 absolutely no warranty for GDB.