gdb_4.html   [plain text]

<!-- This HTML file has been created by texi2html 1.51
     from /mnt/apple/gdb/source/ on 23 November 1999 -->

<TITLE>Debugging with GDB - GDB Commands</TITLE>
Go to the <A HREF="gdb_1.html">first</A>, <A HREF="gdb_3.html">previous</A>, <A HREF="gdb_5.html">next</A>, <A HREF="gdb_21.html">last</A> section, <A HREF="gdb_toc.html">table of contents</A>.

<H1><A NAME="SEC11" HREF="gdb_toc.html#TOC11">GDB Commands</A></H1>

You can abbreviate a GDB command to the first few letters of the command
name, if that abbreviation is unambiguous; and you can repeat certain
GDB commands by typing just <KBD>RET</KBD>.  You can also use the <KBD>TAB</KBD>
key to get GDB to fill out the rest of a word in a command (or to
show you the alternatives available, if there is more than one possibility).


<H2><A NAME="SEC12" HREF="gdb_toc.html#TOC12">Command syntax</A></H2>

A GDB command is a single line of input.  There is no limit on
how long it can be.  It starts with a command name, which is followed by
arguments whose meaning depends on the command name.  For example, the
command <CODE>step</CODE> accepts an argument which is the number of times to
step, as in <SAMP>`step 5'</SAMP>.  You can also use the <CODE>step</CODE> command
with no arguments.  Some command names do not allow any arguments.

<A NAME="IDX15"></A>
GDB command names may always be truncated if that abbreviation is
unambiguous.  Other possible command abbreviations are listed in the
documentation for individual commands.  In some cases, even ambiguous
abbreviations are allowed; for example, <CODE>s</CODE> is specially defined as
equivalent to <CODE>step</CODE> even though there are other commands whose
names start with <CODE>s</CODE>.  You can test abbreviations by using them as
arguments to the <CODE>help</CODE> command.

<A NAME="IDX16"></A>
<A NAME="IDX17"></A>
A blank line as input to GDB (typing just <KBD>RET</KBD>) means to
repeat the previous command. Certain commands (for example, <CODE>run</CODE>)
will not repeat this way; these are commands whose unintentional
repetition might cause trouble and which you are unlikely to want to

The <CODE>list</CODE> and <CODE>x</CODE> commands, when you repeat them with
<KBD>RET</KBD>, construct new arguments rather than repeating
exactly as typed.  This permits easy scanning of source or memory.

GDB can also use <KBD>RET</KBD> in another way: to partition lengthy
output, in a way similar to the common utility <CODE>more</CODE>
(see section <A HREF="gdb_15.html#SEC153">Screen size</A>).  Since it is easy to press one
<KBD>RET</KBD> too many in this situation, GDB disables command
repetition after any command that generates this sort of display.

<A NAME="IDX18"></A>
<A NAME="IDX19"></A>
Any text from a <KBD>#</KBD> to the end of the line is a comment; it does
nothing.  This is useful mainly in command files (see section <A HREF="gdb_16.html#SEC159">Command files</A>).


<H2><A NAME="SEC13" HREF="gdb_toc.html#TOC13">Command completion</A></H2>

<A NAME="IDX20"></A>
<A NAME="IDX21"></A>
GDB can fill in the rest of a word in a command for you, if there is
only one possibility; it can also show you what the valid possibilities
are for the next word in a command, at any time.  This works for GDB
commands, GDB subcommands, and the names of symbols in your program.

Press the <KBD>TAB</KBD> key whenever you want GDB to fill out the rest
of a word.  If there is only one possibility, GDB fills in the
word, and waits for you to finish the command (or press <KBD>RET</KBD> to
enter it).  For example, if you type


(gdb) info bre <KBD>TAB</KBD>

GDB fills in the rest of the word <SAMP>`breakpoints'</SAMP>, since that is
the only <CODE>info</CODE> subcommand beginning with <SAMP>`bre'</SAMP>:


(gdb) info breakpoints

You can either press <KBD>RET</KBD> at this point, to run the <CODE>info
breakpoints</CODE> command, or backspace and enter something else, if
<SAMP>`breakpoints'</SAMP> does not look like the command you expected.  (If you
were sure you wanted <CODE>info breakpoints</CODE> in the first place, you
might as well just type <KBD>RET</KBD> immediately after <SAMP>`info bre'</SAMP>,
to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press
<KBD>TAB</KBD>, GDB sounds a bell.  You can either supply more
characters and try again, or just press <KBD>TAB</KBD> a second time;
GDB displays all the possible completions for that word.  For
example, you might want to set a breakpoint on a subroutine whose name
begins with <SAMP>`make_'</SAMP>, but when you type <KBD>b make_<KBD>TAB</KBD></KBD> GDB
just sounds the bell.  Typing <KBD>TAB</KBD> again displays all the
function names in your program that begin with those characters, for


(gdb) b make_ <KBD>TAB</KBD>
GDB sounds bell; press <KBD>TAB</KBD> again, to see:
make_a_section_from_file     make_environ               
make_abs_section             make_function_type         
make_blockvector             make_pointer_type          
make_cleanup                 make_reference_type        
make_command                 make_symbol_completion_list
(gdb) b make_

After displaying the available possibilities, GDB copies your
partial input (<SAMP>`b make_'</SAMP> in the example) so you can finish the

If you just want to see the list of alternatives in the first place, you
can press <KBD>M-?</KBD> rather than pressing <KBD>TAB</KBD> twice. <KBD>M-?</KBD>
means <KBD><KBD>META</KBD> ?</KBD>.  You can type this either by holding down a
key designated as the <KBD>META</KBD> shift on your keyboard (if there is
one) while typing <KBD>?</KBD>, or as <KBD>ESC</KBD> followed by <KBD>?</KBD>.

<A NAME="IDX22"></A>
<A NAME="IDX23"></A>
Sometimes the string you need, while logically a "word", may contain
parentheses or other characters that GDB normally excludes from
its notion of a word.  To permit word completion to work in this
situation, you may enclose words in <CODE>'</CODE> (single quote marks) in
GDB commands.

The most likely situation where you might need this is in typing the
name of a C++ function.  This is because C++ allows function overloading
(multiple definitions of the same function, distinguished by argument
type).  For example, when you want to set a breakpoint you may need to
distinguish whether you mean the version of <CODE>name</CODE> that takes an
<CODE>int</CODE> parameter, <CODE>name(int)</CODE>, or the version that takes a
<CODE>float</CODE> parameter, <CODE>name(float)</CODE>.  To use the word-completion
facilities in this situation, type a single quote <CODE>'</CODE> at the
beginning of the function name.  This alerts GDB that it may need to
consider more information than usual when you press <KBD>TAB</KBD> or
<KBD>M-?</KBD> to request word completion:


(gdb) b 'bubble( <KBD>M-?</KBD>
bubble(double,double)    bubble(int,int)
(gdb) b 'bubble(

In some cases, GDB can tell that completing a name requires using
quotes.  When this happens, GDB inserts the quote for you (while
completing as much as it can) if you do not type the quote in the first


(gdb) b bub <KBD>TAB</KBD>
GDB alters your input line to the following, and rings a bell:
(gdb) b 'bubble(

In general, GDB can tell that a quote is needed (and inserts it) if
you have not yet started typing the argument list when you ask for
completion on an overloaded symbol.

For more information about overloaded functions, see section <A HREF="gdb_10.html#SEC76">C++ expressions</A>.  You can use the command <CODE>set
overload-resolution off</CODE> to disable overload resolution;
see section <A HREF="gdb_10.html#SEC80">GDB features for C++</A>.


<H2><A NAME="SEC14" HREF="gdb_toc.html#TOC14">Getting help</A></H2>
<A NAME="IDX24"></A>
<A NAME="IDX25"></A>

You can always ask GDB itself for information on its commands, 
using the command <CODE>help</CODE>.


<A NAME="IDX26"></A>
You can use <CODE>help</CODE> (abbreviated <CODE>h</CODE>) with no arguments to
display a short list of named classes of commands:

(gdb) help
List of classes of commands:

running -- Running the program
stack -- Examining the stack
data -- Examining data
breakpoints -- Making program stop at certain points
files -- Specifying and examining files
status -- Status inquiries
support -- Support facilities
user-defined -- User-defined commands
aliases -- Aliases of other commands
obscure -- Obscure features

Type "help" followed by a class name for a list of 
commands in that class.
Type "help" followed by command name for full 
Command name abbreviations are allowed if unambiguous.

<DT><CODE>help <VAR>class</VAR></CODE>
Using one of the general help classes as an argument, you can get a
list of the individual commands in that class.  For example, here is the
help display for the class <CODE>status</CODE>:

(gdb) help status
Status inquiries.

List of commands:

show -- Generic command for showing things set
 with "set"
info -- Generic command for printing status

Type "help" followed by command name for full 
Command name abbreviations are allowed if unambiguous.

<DT><CODE>help <VAR>command</VAR></CODE>
With a command name as <CODE>help</CODE> argument, GDB displays a
short paragraph on how to use that command.

<A NAME="IDX27"></A>
<DT><CODE>complete <VAR>args</VAR></CODE>
The <CODE>complete <VAR>args</VAR></CODE> command lists all the possible completions
for the beginning of a command.  Use <VAR>args</VAR> to specify the beginning of the
command you want completed.  For example:

complete i

results in:


This is intended for use by GNU Emacs.

In addition to <CODE>help</CODE>, you can use the GDB commands <CODE>info</CODE>
and <CODE>show</CODE> to inquire about the state of your program, or the state
of GDB itself.  Each command supports many topics of inquiry; this
manual introduces each of them in the appropriate context.  The listings
under <CODE>info</CODE> and under <CODE>show</CODE> in the Index point to
all the sub-commands.  See section <A HREF="gdb_21.html#SEC170">Index</A>.


<A NAME="IDX28"></A>
 <A NAME="IDX29"></A>
This command (abbreviated <CODE>i</CODE>) is for describing the state of your
program.  For example, you can list the arguments given to your program
with <CODE>info args</CODE>, list the registers currently in use with <CODE>info
registers</CODE>, or list the breakpoints you have set with <CODE>info breakpoints</CODE>.
You can get a complete list of the <CODE>info</CODE> sub-commands with
<CODE>help info</CODE>.

<A NAME="IDX30"></A>
You can assign the result of an expression to an environment variable with 
<CODE>set</CODE>.  For example, you can set the GDB prompt to a $-sign with
<CODE>set prompt $</CODE>.

<A NAME="IDX31"></A>
In contrast to <CODE>info</CODE>, <CODE>show</CODE> is for describing the state of 
GDB itself.
You can change most of the things you can <CODE>show</CODE>, by using the
related command <CODE>set</CODE>; for example, you can control what number
system is used for displays with <CODE>set radix</CODE>, or simply inquire
which is currently in use with <CODE>show radix</CODE>.

<A NAME="IDX32"></A>
To display all the settable parameters and their current
values, you can use <CODE>show</CODE> with no arguments; you may also use
<CODE>info set</CODE>.  Both commands produce the same display.

Here are three miscellaneous <CODE>show</CODE> subcommands, all of which are
exceptional in lacking corresponding <CODE>set</CODE> commands:


<DT><CODE>show version</CODE>
<A NAME="IDX33"></A>
 <A NAME="IDX34"></A>
Show what version of GDB is running.  You should include this
information in GDB bug-reports.  If multiple versions of GDB are in
use at your site, you may occasionally want to determine which version
of GDB you are running; as GDB evolves, new commands are introduced,
and old ones may wither away.  The version number is also announced
when you start GDB.

<A NAME="IDX35"></A>
<DT><CODE>show copying</CODE>
Display information about permission for copying GDB.

<A NAME="IDX36"></A>
<DT><CODE>show warranty</CODE>
Display the GNU "NO WARRANTY" statement.

Go to the <A HREF="gdb_1.html">first</A>, <A HREF="gdb_3.html">previous</A>, <A HREF="gdb_5.html">next</A>, <A HREF="gdb_21.html">last</A> section, <A HREF="gdb_toc.html">table of contents</A>.