gdb/doc/gdb.ctl-m4

   1 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
   2 _dnl__ This file is part of the source for the GDB manual.
   3 @c M4 FRAGMENT: $Id$
   4 @node Controlling _GDBN__, Sequences, Targets, Top
   5 @chapter Controlling _GDBN__
   6
   7 You can alter many aspects of _GDBN__'s interaction with you by using
   8 the @code{set} command.  For commands controlling how _GDBN__ displays
   9 data, @pxref{Print Settings}; other settings are described here.
  10
  11 @menu
  12 * Prompt::                      Prompt
  13 * Editing::                     Command Editing
  14 * History::                     Command History
  15 * Screen Size::                 Screen Size
  16 * Numbers::                     Numbers
  17 * Messages/Warnings::           Optional Warnings and Messages
  18 @end menu
  19
  20 @node Prompt, Editing, Controlling _GDBN__, Controlling _GDBN__
  21 @section Prompt
  22 @cindex prompt
  23 _GDBN__ indicates its readiness to read a command by printing a string
  24 called the @dfn{prompt}.  This string is normally @samp{(_GDBP__)}.  You
  25 can change the prompt string with the @code{set prompt} command.  For
  26 instance, when debugging _GDBN__ with _GDBN__, it is useful to change
  27 the prompt in one of the _GDBN__<>s so that you can always tell which
  28 one you are talking to.
  29
  30 @table @code
  31 @item set prompt @var{newprompt}
  32 @kindex set prompt
  33 Directs _GDBN__ to use @var{newprompt} as its prompt string henceforth.
  34 @kindex show prompt
  35 @item show prompt
  36 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
  37 @end table
  38
  39 @node Editing, History, Prompt, Controlling _GDBN__
  40 @section Command Editing
  41 @cindex readline
  42 @cindex command line editing
  43 _GDBN__ reads its input commands via the @dfn{readline} interface.  This
  44 GNU library provides consistent behavior for programs which provide a
  45 command line interface to the user.  Advantages are @code{emacs}-style
  46 or @code{vi}-style inline editing of commands, @code{csh}-like history
  47 substitution, and a storage and recall of command history across
  48 debugging sessions.
  49
  50 You may control the behavior of command line editing in _GDBN__ with the
  51 command @code{set}.
  52
  53 @table @code
  54 @kindex set editing
  55 @cindex editing
  56 @item set editing
  57 @itemx set editing on
  58 Enable command line editing (enabled by default).
  59
  60 @item set editing off
  61 Disable command line editing.
  62
  63 @kindex show editing
  64 @item show editing
  65 Show whether command line editing is enabled.
  66 @end table
  67
  68 @node History, Screen Size, Editing, Controlling _GDBN__
  69 @section Command History
  70 @table @code
  71 @cindex history substitution
  72 @cindex history file
  73 @kindex set history filename
  74 @item set history filename @var{fname}
  75 Set the name of the _GDBN__ command history file to @var{fname}.  This is
  76 the file from which _GDBN__ will read an initial command history
  77 list or to which it will write this list when it exits.  This list is
  78 accessed through history expansion or through the history
  79 command editing characters listed below.  This file defaults to the
  80 value of the environment variable @code{GDBHISTFILE}, or to
  81 @file{./.gdb_history} if this variable is not set.
  82
  83 @cindex history save
  84 @kindex set history save
  85 @item set history save
  86 @itemx set history save on
  87 Record command history in a file, whose name may be specified with the
  88 @code{set history filename} command.  By default, this option is disabled.
  89
  90 @item set history save off
  91 Stop recording command history in a file.
  92
  93 @cindex history size
  94 @kindex set history size
  95 @item set history size @var{size}
  96 Set the number of commands which _GDBN__ will keep in its history list.
  97 This defaults to the value of the environment variable
  98 @code{HISTSIZE}, or to 256 if this variable is not set.
  99 @end table
 100
 101 @cindex history expansion
 102 History expansion assigns special meaning to the character @kbd{!}.
 103 @iftex
 104 (@xref{Event Designators}.)
 105 @end iftex
 106 Since @kbd{!} is also the logical not operator in C, history expansion
 107 is off by default. If you decide to enable history expansion with the
 108 @code{set history expansion on} command, you may sometimes need to
 109 follow @kbd{!} (when it is used as logical not, in an expression) with
 110 a space or a tab to prevent it from being expanded.  The readline
 111 history facilities will not attempt substitution on the strings
 112 @kbd{!=} and @kbd{!(}, even when history expansion is enabled.
 113
 114 The commands to control history expansion are:
 115
 116 @table @code
 117
 118 @kindex set history expansion
 119 @item set history expansion on
 120 @itemx set history expansion
 121 Enable history expansion.  History expansion is off by default.
 122
 123 @item set history expansion off
 124 Disable history expansion.
 125
 126 The readline code comes with more complete documentation of
 127 editing and history expansion features.  Users unfamiliar with @code{emacs}
 128 or @code{vi} may wish to read it.
 129 @iftex
 130 @xref{Command Line Editing}.
 131 @end iftex
 132
 133 @c @group
 134 @kindex show history
 135 @item show history
 136 @itemx show history filename
 137 @itemx show history save
 138 @itemx show history size
 139 @itemx show history expansion
 140 These commands display the state of the _GDBN__ history parameters.
 141 @code{show history} by itself displays all four states.
 142 @c @end group
 143
 144 @end table
 145
 146 @table @code
 147 @kindex show commands
 148 @item show commands
 149 Display the last ten commands in the command history.
 150
 151 @item show commands @var{n}
 152 Print ten commands centered on command number @var{n}.
 153
 154 @item show commands +
 155 Print ten commands just after the commands last printed.
 156
 157 @end table
 158
 159 @node Screen Size, Numbers, History, Controlling _GDBN__
 160 @section Screen Size
 161 @cindex size of screen
 162 @cindex pauses in output
 163 Certain commands to _GDBN__ may produce large amounts of information
 164 output to the screen.  To help you read all of it, _GDBN__ pauses and
 165 asks you for input at the end of each page of output.  Type @key{RET}
 166 when you want to continue the output.  _GDBN__ also uses the screen
 167 width setting to determine when to wrap lines of output.  Depending on
 168 what is being printed, it tries to break the line at a readable place,
 169 rather than simply letting it overflow onto the following line.
 170
 171 Normally _GDBN__ knows the size of the screen from the termcap data base
 172 together with the value of the @code{TERM} environment variable and the
 173 @code{stty rows} and @code{stty cols} settings. If this is not correct,
 174 you can override it with the @code{set height} and @code{set
 175 width} commands:
 176
 177 @table @code
 178 @item set height @var{lpp}
 179 @itemx show height
 180 @itemx set width @var{cpl}
 181 @itemx show width
 182 @kindex set height
 183 @kindex set width
 184 @kindex show width
 185 @kindex show height
 186 These @code{set} commands specify a screen height of @var{lpp} lines and
 187 a screen width of @var{cpl} characters.  The associated @code{show}
 188 commands display the current settings.
 189
 190 If you specify a height of zero lines, _GDBN__ will not pause during output
 191 no matter how long the output is.  This is useful if output is to a file
 192 or to an editor buffer.
 193 @end table
 194
 195 @node Numbers, Messages/Warnings, Screen Size, Controlling _GDBN__
 196 @section Numbers
 197 @cindex number representation
 198 @cindex entering numbers
 199 You can always enter numbers in octal, decimal, or hexadecimal in _GDBN__ by
 200 the usual conventions: octal numbers begin with @samp{0}, decimal
 201 numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}.
 202 Numbers that begin with none of these are, by default, entered in base
 203 10; likewise, the default display for numbers---when no particular
 204 format is specified---is base 10.  You can change the default base for
 205 both input and output with the @code{set radix} command.
 206
 207 @table @code
 208 @kindex set radix
 209 @item set radix @var{base}
 210 Set the default base for numeric input and display.  Supported choices
 211 for @var{base} are decimal 8, 10, 16.  @var{base} must itself be
 212 specified either unambiguously or using the current default radix; for
 213 example, any of
 214
 215 @example
 216 set radix 012
 217 set radix 10.
 218 set radix 0xa
 219 @end example
 220
 221 @noindent
 222 will set the base to decimal.  On the other hand, @samp{set radix 10}
 223 will leave the radix unchanged no matter what it was.
 224
 225 @kindex show radix
 226 @item show radix
 227 Display the current default base for numeric input and display.
 228
 229 @end table
 230
 231 @node Messages/Warnings,  , Numbers, Controlling _GDBN__
 232 @section Optional Warnings and Messages
 233 By default, _GDBN__ is silent about its inner workings.  If you are running
 234 on a slow machine, you may want to use the @code{set verbose} command.
 235 It will make _GDBN__ tell you when it does a lengthy internal operation, so
 236 you won't think it has crashed.
 237
 238 Currently, the messages controlled by @code{set verbose} are those which
 239 announce that the symbol table for a source file is being read
 240 (@pxref{Files}, in the description of the command
 241 @code{symbol-file}).
 242 @c The following is the right way to do it, but emacs 18.55 doesn't support
 243 @c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo
 244 @c is released.
 245 @ignore
 246 see @code{symbol-file} in @ref{Files}).
 247 @end ignore
 248
 249 @table @code
 250 @kindex set verbose
 251 @item set verbose on
 252 Enables _GDBN__'s output of certain informational messages.
 253
 254 @item set verbose off
 255 Disables _GDBN__'s output of certain informational messages.
 256
 257 @kindex show verbose
 258 @item show verbose
 259 Displays whether @code{set verbose} is on or off.
 260 @end table
 261
 262 By default, if _GDBN__ encounters bugs in the symbol table of an object file,
 263 it prints a single message about each type of problem it finds, then
 264 shuts up (@pxref{Symbol Errors}).  You can suppress these messages, or allow more than one such
 265 message to be printed if you want to see how frequent the problems are.
 266
 267 @table @code
 268 @kindex set complaints
 269 @item set complaints @var{limit}
 270 Permits _GDBN__ to output @var{limit} complaints about each type of unusual
 271 symbols before becoming silent about the problem.  Set @var{limit} to
 272 zero to suppress all complaints; set it to a large number to prevent
 273 complaints from being suppressed.
 274
 275 @kindex show complaints
 276 @item show complaints
 277 Displays how many symbol complaints _GDBN__ is permitted to produce.
 278 @end table
 279
 280 By default, _GDBN__ is cautious, and asks what sometimes seem to be a
 281 lot of stupid questions to confirm certain commands.  For example, if
 282 you try to run a program which is already running:
 283 @example
 284 (_GDBP__) run
 285 The program being debugged has been started already.
 286 Start it from the beginning? (y or n)
 287 @end example
 288
 289 If you're willing to unflinchingly face the consequences of your own
 290 commands, you can disable this ``feature'':
 291
 292 @table @code
 293 @kindex set confirm
 294 @cindex flinching
 295 @cindex confirmation
 296 @cindex stupid questions
 297 @item set confirm off
 298 Disables confirmation requests.
 299
 300 @item set confirm on
 301 Enables confirmation requests (the default).
 302
 303 @item show confirm
 304 @kindex show confirm
 305 Displays state of confirmation requests.
 306 @end table