binutils-gdb/gdb/doc/gdb.ctl-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 Controlling _GDBN__, Sequences, Targets, Top
@chapter Controlling _GDBN__

You can alter many aspects of _GDBN__'s interaction with you by using
the @code{set} command.  For commands controlling how _GDBN__ displays
data, @pxref{Print Settings}; other settings are described here.

@menu
* Prompt::			Prompt
* Editing::			Command Editing
* History::			Command History
* Screen Size::			Screen Size
* Numbers::			Numbers
* Messages/Warnings::		Optional Warnings and Messages
@end menu

@node Prompt, Editing, Controlling _GDBN__, Controlling _GDBN__
@section Prompt
@cindex prompt
_GDBN__ indicates its readiness to read a command by printing a string
called the @dfn{prompt}.  This string is normally @samp{(_GDBP__)}.  You
can change the prompt string with the @code{set prompt} command.  For
instance, when debugging _GDBN__ with _GDBN__, it is useful to change
the prompt in one of the _GDBN__<>s so that you can always tell which
one you are talking to.

@table @code
@item set prompt @var{newprompt}
@kindex set prompt
Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth.
@kindex show prompt
@item show prompt
Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
@end table

@node Editing, History, Prompt, Controlling _GDBN__
@section Command Editing
@cindex readline
@cindex command line editing
_GDBN__ reads its input commands via the @dfn{readline} interface.  This
GNU library provides consistent behavior for programs which provide a
command line interface to the user.  Advantages are @code{emacs}-style
or @code{vi}-style inline editing of commands, @code{csh}-like history
substitution, and a storage and recall of command history across
debugging sessions.

You may control the behavior of command line editing in _GDBN__ with the
command @code{set}.  

@table @code
@kindex set editing
@cindex editing
@item set editing
@itemx set editing on
Enable command line editing (enabled by default).

@item set editing off
Disable command line editing.

@kindex show editing
@item show editing
Show whether command line editing is enabled.
@end table

@node History, Screen Size, Editing, Controlling _GDBN__
@section Command History
@table @code
@cindex history substitution
@cindex history file
@kindex set history filename
@item set history filename @var{fname}
Set the name of the _GDBN__ command history file to @var{fname}.  This is
the file from which _GDBN__ will read an initial command history
list or to which it will write this list when it exits.  This list is
accessed through history expansion or through the history
command editing characters listed below.  This file defaults to the
value of the environment variable @code{GDBHISTFILE}, or to
@file{./.gdb_history} if this variable is not set.

@cindex history save
@kindex set history save
@item set history save
@itemx set history save on
Record command history in a file, whose name may be specified with the
@code{set history filename} command.  By default, this option is disabled.

@item set history save off
Stop recording command history in a file.

@cindex history size
@kindex set history size
@item set history size @var{size}
Set the number of commands which _GDBN__ will keep in its history list.
This defaults to the value of the environment variable
@code{HISTSIZE}, or to 256 if this variable is not set.
@end table

@cindex history expansion
History expansion assigns special meaning to the character @kbd{!}.
@iftex
(@xref{Event Designators}.)
@end iftex
Since @kbd{!} is also the logical not operator in C, history expansion
is off by default. If you decide to enable history expansion with the
@code{set history expansion on} command, you may sometimes need to
follow @kbd{!} (when it is used as logical not, in an expression) with
a space or a tab to prevent it from being expanded.  The readline
history facilities will not attempt substitution on the strings
@kbd{!=} and @kbd{!(}, even when history expansion is enabled.

The commands to control history expansion are:

@table @code

@kindex set history expansion
@item set history expansion on
@itemx set history expansion
Enable history expansion.  History expansion is off by default.

@item set history expansion off
Disable history expansion.

The readline code comes with more complete documentation of
editing and history expansion features.  Users unfamiliar with @code{emacs}
or @code{vi} may wish to read it. 
@iftex
@xref{Command Line Editing}.
@end iftex

@c @group
@kindex show history
@item show history
@itemx show history filename
@itemx show history save
@itemx show history size
@itemx show history expansion
These commands display the state of the _GDBN__ history parameters.
@code{show history} by itself displays all four states.
@c @end group

@end table

@table @code
@kindex show commands
@item show commands
Display the last ten commands in the command history.

@item show commands @var{n}
Print ten commands centered on command number @var{n}.

@item show commands +
Print ten commands just after the commands last printed.

@end table

@node Screen Size, Numbers, History, Controlling _GDBN__
@section Screen Size
@cindex size of screen
@cindex pauses in output
Certain commands to _GDBN__ may produce large amounts of information
output to the screen.  To help you read all of it, _GDBN__ pauses and
asks you for input at the end of each page of output.  Type @key{RET}
when you want to continue the output.  _GDBN__ also uses the screen
width setting to determine when to wrap lines of output.  Depending on
what is being printed, it tries to break the line at a readable place,
rather than simply letting it overflow onto the following line.

Normally _GDBN__ knows the size of the screen from the termcap data base
together with the value of the @code{TERM} environment variable and the
@code{stty rows} and @code{stty cols} settings. If this is not correct,
you can override it with the @code{set height} and @code{set
width} commands:

@table @code
@item set height @var{lpp}
@itemx show height
@itemx set width @var{cpl}
@itemx show width
@kindex set height
@kindex set width
@kindex show width
@kindex show height
These @code{set} commands specify a screen height of @var{lpp} lines and
a screen width of @var{cpl} characters.  The associated @code{show}
commands display the current settings.

If you specify a height of zero lines, _GDBN__ will not pause during output
no matter how long the output is.  This is useful if output is to a file
or to an editor buffer.
@end table

@node Numbers, Messages/Warnings, Screen Size, Controlling _GDBN__
@section Numbers
@cindex number representation
@cindex entering numbers
You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by
the usual conventions: octal numbers begin with @samp{0}, decimal
numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
Numbers that begin with none of these are, by default, entered in base
10; likewise, the default display for numbers---when no particular
format is specified---is base 10.  You can change the default base for
both input and output with the @code{set radix} command.

@table @code
@kindex set radix
@item set radix @var{base}
Set the default base for numeric input and display.  Supported choices
for @var{base} are decimal 8, 10, 16.  @var{base} must itself be
specified either unambiguously or using the current default radix; for
example, any of

@example
set radix 012
set radix 10.
set radix 0xa
@end example

@noindent
will set the base to decimal.  On the other hand, @samp{set radix 10}
will leave the radix unchanged no matter what it was.

@kindex show radix
@item show radix
Display the current default base for numeric input and display.

@end table

@node Messages/Warnings,  , Numbers, Controlling _GDBN__
@section Optional Warnings and Messages
By default, _GDBN__ is silent about its inner workings.  If you are running
on a slow machine, you may want to use the @code{set verbose} command.
It will make _GDBN__ tell you when it does a lengthy internal operation, so
you won't think it has crashed.

Currently, the messages controlled by @code{set verbose} are those which
announce that the symbol table for a source file is being read
(@pxref{Files}, in the description of the command
@code{symbol-file}).
@c The following is the right way to do it, but emacs 18.55 doesn't support
@c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
@c is released.  
@ignore
see @code{symbol-file} in @ref{Files}).
@end ignore

@table @code
@kindex set verbose
@item set verbose on
Enables _GDBN__'s output of certain informational messages.

@item set verbose off
Disables _GDBN__'s output of certain informational messages.

@kindex show verbose
@item show verbose
Displays whether @code{set verbose} is on or off.
@end table

By default, if _GDBN__ encounters bugs in the symbol table of an object file,
it prints a single message about each type of problem it finds, then 
shuts up (@pxref{Symbol Errors}).  You can suppress these messages, or allow more than one such
message to be printed if you want to see how frequent the problems are.

@table @code
@kindex set complaints
@item set complaints @var{limit}
Permits _GDBN__ to output @var{limit} complaints about each type of unusual
symbols before becoming silent about the problem.  Set @var{limit} to
zero to suppress all complaints; set it to a large number to prevent
complaints from being suppressed.

@kindex show complaints
@item show complaints
Displays how many symbol complaints _GDBN__ is permitted to produce.
@end table

By default, _GDBN__ is cautious, and asks what sometimes seem to be a
lot of stupid questions to confirm certain commands.  For example, if
you try to run a program which is already running:
@example
(_GDBP__) run
The program being debugged has been started already.
Start it from the beginning? (y or n) 
@end example

If you're willing to unflinchingly face the consequences of your own
commands, you can disable this ``feature'':

@table @code
@kindex set confirm
@cindex flinching
@cindex confirmation
@cindex stupid questions
@item set confirm off
Disables confirmation requests.

@item set confirm on
Enables confirmation requests (the default).

@item show confirm
@kindex show confirm
Displays state of confirmation requests.
@end table