binutils-gdb/gdb/doc/gdb.cmds-m4

_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
_dnl__ This file is part of the source for the GDB manual.
@c M4 FRAGMENT: $Id$
@node Commands, Running, Invocation, Top
@chapter _GDBN__ Commands

@menu
* Command Syntax::		Command Syntax
* Help::			Getting Help
@end menu

@node Command Syntax, Help, Commands, Commands
@section Command Syntax
A _GDBN__ 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} accepts an argument which is the number of times to step,
as in @samp{step 5}.  You can also use the @code{step} command with
no arguments.  Some command names do not allow any arguments.

@cindex abbreviation
_GDBN__ command names may always be truncated if that abbreviation is
unambiguous.  Other possible command abbreviations are listed in the
documentation for individual commands.  Sometimes even ambiguous
abbreviations are allowed; for example, @code{s} is specially defined as
equivalent to @code{step} even though there are other commands whose
names start with @code{s}.

@cindex repeating commands
A blank line as input to _GDBN__ means to repeat the previous command.
Certain commands (for example, @code{run}) will not repeat this way;
these are commands for which unintentional repetition might cause
trouble and which you are unlikely to want to repeat.

The @code{list} and @code{x} commands construct new arguments when
repeated, rather than repeating exactly as typed, to permit easy
scanning of source or memory.

@kindex #
@cindex comment
A line of input starting with @kbd{#} is a comment; it does nothing.
This is useful mainly in command files (@xref{Command Files}).

@node Help,  , Command Syntax, Commands
@section Getting Help
@cindex online documentation
@kindex help
You can always ask _GDBN__ itself for information on its commands, using the
command @code{help}.  

@table @code
@item help
@itemx h
@kindex h
You can use @code{help} (abbreviated @code{h}) with no arguments to
display a short list of named categories of commands:
@smallexample
(_GDBP__) 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 documentation.
Command name abbreviations are allowed if unambiguous.
(_GDBP__) 
@end smallexample

@item help @var{category}
Using one of the general help categories as an argument, you can get a
list of the individual commands in a category.  For example, here is the
help display for category @code{status}:
@smallexample
(_GDBP__) 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 documentation.
Command name abbreviations are allowed if unambiguous.
(_GDBP__) 
@end smallexample

@item help @var{command}
With a command name as @code{help} argument, _GDBN__ will display a
short paragraph on how to use that command.  
@end table

In addition to @code{help}, you can use the _GDBN__ commands @code{info}
and @code{show} to inquire about the state of your program, or the state
of _GDBN__ itself.  Both commands support many topics of inquiry; this
manual introduces each of them in the appropriate context.  The listings
under @code{info} and under @code{show} in the Index point to
all the sub-commands.
@c FIXME: @pxref{Index} used to be here, but even though it shows up in
@c FIXME...the 'aux' file with a pageno the xref can't find it.  

@c @group
@table @code
@item info
@kindex info
@kindex i
This command (abbreviated @code{i}) is for describing the state of your
program; for example, it can list the arguments given to your program
(@code{info args}), the registers currently in use (@code{info
registers}), or the breakpoints you've set (@code{info breakpoints}).
You can get a complete list of the @code{info} sub-commands with
@w{@code{help info}}.

@kindex show
@item show
In contrast, @code{show} is for describing the state of _GDBN__ itself.
You can change most of the things you can @code{show}, by using the
related command @code{set}; for example, you can control what number
system is used for displays with @code{set radix}, or simply inquire
which is currently in use with @code{show radix}.  

@kindex info set
To display all the settable parameters and their current
values, you can use @code{show} with no arguments; you may also use
@code{info set}.  Both commands produce the same display.
@c FIXME: "info set" violates the rule that "info" is for state of
@c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
@end table
@c @end group

Here are three miscellaneous @code{show} subcommands, all of which are
exceptional in lacking corresponding @code{set} commands:

@table @code
@kindex show version
@item show version
Show what version of _GDBN__ is running.  You should include this
information in _GDBN__ bug-reports.  If multiple versions of _GDBN__ are
in use at your site, you may occasionally want to make sure what version
of _GDBN__ you're running; as _GDBN__ evolves, new commands are
introduced, and old ones may wither away.  The version number is also
announced when you start _GDBN__ with no arguments.

@kindex show copying
@item show copying
Display information about permission for copying _GDBN__.

@kindex show warranty
@item show warranty
Display the GNU ``NO WARRANTY'' statement.
@end table