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