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.
41 % The GDB-under-Emacs section omits gdb-mode functions without default
42 % keybindings. GDB startup options are not described.
47 \def\$
#1$
{{#1}}% Kluge: collect RCS revision info without $...$
48 \xdef\manvers{\$Revision$
}%
51 \hyphenpenalty=
5000\tolerance=
2000\raggedright\raggedbottom
53 %The Times-Roman family is used below because it is both more
54 %attractive and more compact than Computer Modern. On the other hand,
55 %while common, it is not Free. The commented-out font definitions
56 %will be close (but may cause some column overflows) if you must use
59 \font\bbf=Times-Bold at
10pt
61 \font\vbbf=Times-Bold at
12pt
63 \font\smrm=Times-Roman at
6pt
65 \font\brm=Times-Roman at
10pt
67 \font\rm=Times-Roman at
8pt
69 \font\it=Times-Italic at
8pt
70 % We *do* use CMtt rather than Courier because TeX and PS fonts have
71 % different ideas about where ``funny'' chars go.
73 % Finally, the following common-but-not-free font (Symbol) is used
74 % only for the copyright symbol. Comment out the whole definition of
75 % \copyright if you insist on using only Free fonts, and you'll pick
76 % up the kluge in plain.tex that defines \copyright by overstriking.
77 \font\sym=Symbol at
7pt
78 \def\copyright{{\sym\char'
323}}
79 \normalbaselineskip=
9pt
\baselineskip=
9pt
83 \footline=
{\vbox to0pt
{\hss}}
85 \def\ctl#1{{\tt C-
#1}}
86 \def\opt#1{{\brm[{\rm #1}]}}
87 \def\xtra#1{\noalign{\smallskip{\tt#1}}}
89 \long\def\sec#1;
#2\endsec{\vskip 1pc
96 &
\vtop{\hsize=
2.1in
\hangafter=
1\hangindent=
0.5em
97 \rm ##
\par\vskip 2pt
}\cr
98 %Tail of \long\def fills in halign body with \sec args:
99 \noalign{{\bbf #1}\vskip 2pt
}
104 {\vbbf GDB QUICK REFERENCE
}
106 {\smrm GDB Version
4.0---Cygnus Support
1991}
108 \sec Essential Commands;
109 gdb
{\it program
} \opt{{\it core
}}&debug
{\it program
} \opt{using
110 coredump
{\it core
}}\cr
111 bt& backtrace: display program stack
\cr
112 b
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it function
} \opt{in
\it file
}\cr
113 run
\opt{{\it arglist
}}&start your program
\opt{with
{\it arglist
}}\cr
114 p
{\it expr
}&display the value of an expression
\cr
115 c &continue running your program
\cr
116 n &execute next line, including function calls
\cr
117 s &execute until another line is reached
\cr
121 gdb&starts GDB, with no debugging files
\cr
122 gdb
{\it program
}&begin debugging
{\it program
}\cr
123 gdb
{\it program core
}&debug coredump
{\it core
} produced by
{\it program
}\cr
127 quit&exit GDB; also
{\tt q
} or
{\tt EOF
} (eg
\ctl{d
})
\cr
128 INTERRUPT&(eg
\ctl{c
}) terminate current command, or send to running process
\cr
132 help&list classes of commands
\cr
133 help
{\it class
}&one-line descriptions for commands in
{\it class
}\cr
134 help
{\it command
}&describe
{\it command
}\cr
137 \sec Executing your Program;
138 run
{\it arglist
}&start your program with
{\it arglist
}\cr
139 run&start your program with current argument list
\cr
140 run $
\ldots$ <
{\it inf
} >
{\it outf
}&start program with input, output
143 kill&kill running program
\cr
145 tty
{\it dev
}&use
{\it dev
} as stdin and stdout for next
{\tt run
}\cr
146 set args
{\it arglist
}&specify
{\it arglist
} for next
148 set args&specify empty argument list
\cr
149 show args&display argument list
\cr
151 show environment&show all environment variables
\cr
152 show env
{\it var
}&show value of environment variable
{\it var
}\cr
153 set env
{\it var
} {\it string
}&set environment variable
{\it var
}\cr
154 unset env
{\it var
}&remove
{\it var
} from environment
\cr
158 cd
{\it dir
}&change working directory to
{\it dir
}\cr
159 pwd&Print working directory
\cr
160 make $
\ldots$&call ``
{\tt make
}''
\cr
161 shell
{\it cmd
}&execute arbitrary shell command string
\cr
165 \centerline{\smrm \copyright 1991 Free Software Foundation, Inc.
\qquad Permissions on back
}
167 \sec Breakpoints and Watchpoints;
168 break
\opt{\it file
\tt:
}{\it line
}\par
169 b
\opt{\it file
\tt:
}{\it line
}&set breakpoint at
{\it line
} number
\opt{in
\it file
}\par
170 eg:
\quad{\tt break main.c:
37}\quad\cr
171 break
\opt{\it file
\tt:
}{\it function
}&set breakpoint at
{\it
172 function
} \opt{in
\it file
}\cr
173 break +
{\it offset
}\par
174 break -
{\it offset
}&set break at
{\it offset
} lines from current stop
\cr
175 break *
{\it addr
}&set breakpoint at address
{\it addr
}\cr
176 break&set breakpoint at next instruction
\cr
177 break $
\ldots$ if
{\it expr
}&break conditionally on nonzero
{\it expr
}\cr
178 cond
{\it n
} \opt{\it expr
}&new conditional expression on breakpoint
179 {\it n
}; make unconditional if no
{\it expr
}\cr
180 tbreak $
\ldots$&temporary break; disable when reached
\cr
181 rbreak
{\it regex
}&break on all functions matching
{\it regex
}\cr
182 watch
{\it expr
}&set a watchpoint for expression
{\it expr
}\cr
183 catch
{\it x
}&break at C++ handler for exception
{\it x
}\cr
185 info break&show defined breakpoints
\cr
186 info watch&show defined watchpoints
\cr
188 clear&delete breakpoints at next instruction
\cr
189 clear
\opt{\it file
\tt:
}{\it fun
}&delete breakpoints at entry to
{\it fun
}()
\cr
190 clear
\opt{\it file
\tt:
}{\it line
}&delete breakpoints on source line
\cr
191 delete
\opt{{\it n
}}&delete breakpoints
{\it n
};
192 \opt{or all breakpoints
}\cr
194 disable
\opt{{\it n
}}&disable breakpoints
{\it n
} \opt{or all
}\cr
195 enable
\opt{{\it n
}}&enable breakpoints
{\it n
} \opt{or all
}\cr
196 enable once
\opt{{\it n
}}&enable breakpoints; disable again when
198 enable del
\opt{{\it n
}}&enable breakpoints; delete when reached
\cr
200 ignore
{\it n
} {\it count
}&ignore breakpoint
{\it n
},
{\it count
}
204 \qquad {\it command list
}&execute GDB
{\it command list
} every time breakpoint
{\it n
} is reached
\cr
205 end&end of
{\it command list
}\cr
209 backtrace
\opt{\it n
}\par
210 bt
\opt{\it n
}&print trace of all frames in stack; or of
{\it n
}
211 frames---innermost if
{\it n
}{\tt >
0}, outermost if
{\it n
}{\tt <
0}\cr
212 frame
\opt{\it n
}&select frame number
{\it n
} or frame at address
{\it
213 n
}; if no
{\it n
}, display current frame
\cr
214 up
{\it n
}&select frame
{\it n
} frames up
\cr
215 down
{\it n
}&select frame
{\it n
} frames down
\cr
216 info frame
\opt{\it addr
}&describe selected frame, or frame at
218 info args&arguments of selected frame
\cr
219 info locals&local variables of selected frame
\cr
220 info reg
\opt{\it{rn
}}®ister values
\opt{for reg
{\it rn\/
}} in selected frame
\cr
221 info catch&exception handlers active in selected frame
\cr
225 \sec Execution Control;
226 continue
\opt{\it count
}\par
227 c
\opt{\it count
}&continue running; if
{\it count
} specified, ignore
228 this breakpoint next
{\it count
} times
\cr
230 step
\opt{\it count
}\par
231 s
\opt{\it count
}&execute until another line reached; repeat
{\it count
} times if
234 stepi
\opt{\it count
}\par
235 si
\opt{\it count
}&step by machine instructions rather than source
238 next
\opt{\it count
}\par
239 n
\opt{\it count
}&execute next line, including any function calls
\cr
241 nexti
\opt{\it count
}\par
242 ni
\opt{\it count
}&next machine instruction rather than source
245 until
\opt{\it location
}&run until next instruction (or
{\it
247 finish&run until selected stack frame returns
\cr
248 return
\opt{\it expr
}&pop selected stack frame without executing
249 \opt{setting return value
}\cr
250 signal
{\it num
}&resume execution with signal
{\it s
} (none if
{\tt 0})
\cr
252 jump *
{\it address
}&resume execution at specified
{\it line
} number or
254 set var=
{\it expr
}&evaluate
{\it expr
} without displaying it; use for
255 altering program variables
\cr
259 print
\opt{\tt/
{\it f
}\/
} {\it expr
}\par
260 p
\opt{\tt/
{\it f
}\/
} {\it expr
}&show value of
{\it expr
} according to format
{\it f
}:
\cr
261 \qquad x&hexadecimal
\cr
262 \qquad d&signed decimal
\cr
263 \qquad u&unsigned decimal
\cr
265 \qquad a&address, absolute and relative
\cr
266 \qquad c&character
\cr
267 \qquad f&floating point
\cr
268 call
\opt{\tt /
{\it f
}\/
} {\it expr
}&like
{\tt print
} but does not display
270 x
\opt{\tt/
{\it Nuf
}\/
} {\it expr
}&examine memory at address
{\it expr
};
271 optional format spec follows slash
\cr
272 \quad {\it N
}&count of how many units to display
\cr
273 \quad {\it u
}&unit size; one of
\cr
274 &
{\tt\qquad b
}\ individual bytes
\cr
275 &
{\tt\qquad h
}\ halfwords (two bytes)
\cr
276 &
{\tt\qquad w
}\ words (four bytes)
\cr
277 &
{\tt\qquad g
}\ giant words (eight bytes)
\cr
278 \quad {\it f
}&printing format. Any
{\tt print
} format, or
\cr
279 &
{\tt\qquad s
}\ null-terminated string
\cr
280 &
{\tt\qquad i
}\ machine instructions
\cr
281 disassemble
\opt{\it addr
}&display memory as machine instructions
\cr
284 \sec Automatic Display;
285 display
\opt{\tt/
\it f\/
} {\it expr
}&show value of
{\it expr
} each time
286 program stops
\opt{according to format
{\it f
}\/
}\cr
287 display&display all enabled expressions on list
\cr
288 undisplay
{\it n
}&remove number(s)
{\it n
} from list of
289 automatically displayed expressions
\cr
290 disable display
{\it n
}&disable display for expression(s) number
{\it
292 enable display
{\it n
}&enable display for expression(s) number
{\it
294 info display&numbered list of display expressions
\cr
300 {\it expr
}&an expression in C or C++ (including function calls), or:
\cr
301 {\it addr\/
}@
{\it len
}&an array of
{\it len
} elements beginning at
{\it
303 {\it file
}::
{\it nm
}&a variable or function
{\it nm
} defined in
{\it
305 $
\tt\
{$
{\it type
}$
\tt\
}$
{\it addr
}&read memory at
{\it addr
} as specified
307 \$&most recent displayed value
\cr
308 \$
{\it n
}&
{\it n
}th displayed value
\cr
309 \$\$&displayed value previous to \$
\cr
310 \$\$
{\it n
}&
{\it n
}th displayed value back from \$
\cr
311 \$
\_&last address examined with
{\tt x
}\cr
312 \$
\_\_&value at address \$
\_\cr
313 \$
{\it var
}&convenience variable; assign any value
\cr
315 show values
\opt{{\it n
}}&show last
10 values
\opt{or surrounding
317 show convenience&display all convenience variables
\cr
321 info address
{\it s
}&show where symbol
{\it s
} is stored
\cr
322 info func
\opt{\it regex
}&show names, types of defined functions
323 (all, or matching
{\it regex
})
\cr
324 info var
\opt{\it regex
}&show names, types of global variables (all,
325 or matching
{\it regex
})
\cr
326 whatis
{\it expr
}\par
327 ptype
{\it expr
}&show data type of
{\it expr
} without evaluating;
{\tt
328 ptype
} gives more detail
\cr
329 ptype
{\it type
}&describe type, struct, union, or enum
\cr
333 source
{\it script
}&read, execute GDB commands from file
{\it
337 \qquad {\it command list
}&new GDB command
{\it cmd
}, executes script
338 defined by
{\it command list
} \cr
339 end&end of
{\it command list
}\cr
340 document {\it cmd
}\par
341 \qquad {\it help text
}&new online documentation for GDB command
{\it
343 end&end of
{\it help text
}\cr
347 handle
{\it signal
} {\it act
}&specify GDB actions when
{\it signal
} occurs:
\cr
348 \quad print&announce when signal occurs
\cr
349 \quad noprint&be silent when signal occurs
\cr
350 \quad stop&halt execution on signal
\cr
351 \quad nostop&do not halt execution
\cr
352 \quad pass&allow your program to handle signal
\cr
353 \quad nopass&do not allow your program to see signal
\cr
354 info signals&show table of signals, GDB action for each
\cr
357 \sec Debugging Targets;
358 target
{\it type
} {\it param
}&connect to target machine, process, or file
\cr
359 help target&display available targets
\cr
360 attach
{\it param
}&connect to another process
\cr
361 detach&release target from GDB control
\cr
365 \sec Controlling GDB;
366 set
{\it param
} {\it expr
}&set one of GDB's internal parameters
\cr
367 show
{\it param
}&display current setting of a GDB parameter
\cr
368 \xtra{\rm Parameters understood by
{\tt set
} and
{\tt show
}:
}
369 \quad complaints
{\it limit
}&number of messages on unusual symbols
\cr
370 \quad confirm
{\it on/off
}&enable or disable cautionary queries
\cr
371 \quad editing
{\it on/off
}&control
{\tt readline
} command-line editing
\cr
372 \quad height
{\it lpp
}&number of lines before pause in
374 \quad prompt
{\it str
}&use
{\it str
} as GDB prompt
\cr
375 \quad radix
{\it base
}&octal, decimal, or hex number representation
\cr
376 \quad verbose
{\it on/off
}&control messages when loading
378 \quad width
{\it cpl
}&number of characters before line folded
\cr
380 \quad history $
\ldots$&(
{\tt h
}) groups the following options:
\cr
381 \quad h exp
{\it off/on
}&disable or enable
{\tt readline
} history expansion
\cr
382 \quad h file
{\it filename
}&file for recording GDB command history
\cr
383 \quad h size
{\it size
}&number of commands kept in history list
\cr
384 \quad h save
{\it off/on
}&control use of external file for
387 \quad print $
\ldots$&(
{\tt p
}) groups the following options:
\cr
388 \quad p address
{\it on/off
}&print memory addresses in stacks,
390 \quad p array
{\it off/on
}&compact or attractive format for
392 \quad p demangle
{\it on/off
}&source or internal form for C++
394 \quad p asm-dem
{\it on/off
}&demangle C++ symbols in
395 machine-instruction output
\cr
396 \quad p elements
{\it limit
}&number of elements to display from an
398 \quad p object
{\it on/off
}&print C++ derived types for objects
\cr
399 \quad p pretty
{\it off/on
}&struct display: compact or indented
\cr
400 \quad p union
{\it on/off
}&enable or disable display of union members
\cr
401 \quad p vtbl
{\it off/on
}&display of C++ virtual function
404 show commands&show last
10 commands
\cr
405 show commands
{\it n
}&show
10 commands around number
{\it n
}\cr
406 show commands +&show next
10 commands
\cr
410 file
{\it name
}&use
{\it file
} for symbols and executable
\cr
411 core
{\it name
}&read
{\it file
} as coredump
\cr
412 exec
{\it name
}&use
{\it file
} as executable only
\cr
413 symbol
{\it name
}&use only symbol table from
{\it file
}\cr
414 load
{\it file
}&dynamically link
{\it file\/
} and add its symbols
\cr
415 add-sym
{\it file
} {\it addr
}&read additional symbols from
{\it file
},
416 dynamically loaded at
{\it addr
}\cr
417 info files&display working files and targets in use
\cr
418 path
{\it dirs
}&add
{\it dirs
} to front of path searched for
419 executable and symbol files
\cr
420 info path&display executable and symbol file path
\cr
421 share
\opt{\it regex
}&add symbol information for shared libraries
422 matching
{\it regex
}, or all shared libraries
\cr
423 info share&list names of shared libraries currently loaded
\cr
428 dir
{\it names
}&add directory
{\it names
} to front of source path
\cr
429 dir&clear source path
\cr
430 show dir&show current source path
\cr
432 list&show next ten lines of source
\cr
433 list -&show previous ten lines
\cr
434 list
{\it lines
}&display source centered around
{\it lines
},
435 specified as one of:
\cr
436 \quad{\opt{\it file
\tt:
}\it num
}&line number
\opt{in named file
}\cr
437 \quad{\opt{\it file
\tt:
}\it function
}&beginning of function
\opt{in
439 \quad{\tt +
\it off
}&
{\it off
} lines after last printed
\cr
440 \quad{\tt -
\it off
}&
{\it off
} lines previous to last printed
\cr
441 \quad{\tt*
\it address
}&line containing
{\it address
}\cr
442 list
{\it f
},
{\it l
}&from line
{\it f
} to line
{\it l
}\cr
443 info line
{\it num
}&show starting, ending addresses of compiled code for
444 source line
{\it num
}\cr
445 info source&show name of current source file
\cr
446 info sources&list all source files in use
\cr
447 forw
{\it regex
}&search following source lines for
{\it regex
}\cr
448 rev
{\it regex
}&search preceding source lines for
{\it regex
}\cr
451 \sec GDB under GNU Emacs;
452 M-x gdb&run GDB under Emacs
\cr
453 \ctl{h
} m&describe GDB mode
\cr
454 M-s&step one line (
{\tt step
})
\cr
455 M-n&next line (
{\tt next
})
\cr
456 M-i&step one instruction (
{\tt stepi
})
\cr
457 \ctl{c
} \ctl{f
}&finish current stack frame (
{\tt finish
})
\cr
458 M-c&continue (
{\tt cont
})
\cr
459 M-u&up
{\it arg
} frames (
{\tt up
})
\cr
460 M-d&down
{\it arg
} frames (
{\tt down
})
\cr
461 \ctl{x
} \&© number from point, insert at end
\cr
462 \ctl{x
} SPC&(in source file) set break at point
\cr
468 \centerline{Copyright
\copyright 1991 Free Software Foundation, Inc.
}
469 \centerline{Roland Pesch (pesch@cygnus.com), May
1991---
\manvers}
470 \centerline{The author assumes no responsibility for any errors on this card.
}
472 This card may be freely distributed under the terms of the GNU
473 General Public License.
475 \centerline{Please contribute to development of this card by annotating it.
}