gdb/doc/gdb.cmds-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 Commands, Running, Invocation, Top
   5 @chapter _GDBN__ Commands
   6
   7 @menu
   8 * Command Syntax::              Command Syntax
   9 * Help::                        Getting Help
  10 @end menu
  11
  12 @node Command Syntax, Help, Commands, Commands
  13 @section Command Syntax
  14 A _GDBN__ command is a single line of input.  There is no limit on how long
  15 it can be.  It starts with a command name, which is followed by arguments
  16 whose meaning depends on the command name.  For example, the command
  17 @code{step} accepts an argument which is the number of times to step,
  18 as in @samp{step 5}.  You can also use the @code{step} command with
  19 no arguments.  Some command names do not allow any arguments.
  20
  21 @cindex abbreviation
  22 _GDBN__ command names may always be truncated if that abbreviation is
  23 unambiguous.  Other possible command abbreviations are listed in the
  24 documentation for individual commands.  Sometimes even ambiguous
  25 abbreviations are allowed; for example, @code{s} is specially defined as
  26 equivalent to @code{step} even though there are other commands whose
  27 names start with @code{s}.
  28
  29 @cindex repeating commands
  30 A blank line as input to _GDBN__ means to repeat the previous command.
  31 Certain commands (for example, @code{run}) will not repeat this way;
  32 these are commands for which unintentional repetition might cause
  33 trouble and which you are unlikely to want to repeat.
  34
  35 The @code{list} and @code{x} commands construct new arguments when
  36 repeated, rather than repeating exactly as typed, to permit easy
  37 scanning of source or memory.
  38
  39 @kindex #
  40 @cindex comment
  41 A line of input starting with @kbd{#} is a comment; it does nothing.
  42 This is useful mainly in command files (@xref{Command Files}).
  43
  44 @node Help,  , Command Syntax, Commands
  45 @section Getting Help
  46 @cindex online documentation
  47 @kindex help
  48 You can always ask _GDBN__ itself for information on its commands, using the
  49 command @code{help}.
  50
  51 @table @code
  52 @item help
  53 @itemx h
  54 @kindex h
  55 You can use @code{help} (abbreviated @code{h}) with no arguments to
  56 display a short list of named categories of commands:
  57 @smallexample
  58 (_GDBP__) help
  59 List of classes of commands:
  60
  61 running -- Running the program
  62 stack -- Examining the stack
  63 data -- Examining data
  64 breakpoints -- Making program stop at certain points
  65 files -- Specifying and examining files
  66 status -- Status inquiries
  67 support -- Support facilities
  68 user-defined -- User-defined commands
  69 aliases -- Aliases of other commands
  70 obscure -- Obscure features
  71
  72 Type "help" followed by a class name for a list of commands in that class.
  73 Type "help" followed by command name for full documentation.
  74 Command name abbreviations are allowed if unambiguous.
  75 (_GDBP__)
  76 @end smallexample
  77
  78 @item help @var{category}
  79 Using one of the general help categories as an argument, you can get a
  80 list of the individual commands in a category.  For example, here is the
  81 help display for category @code{status}:
  82 @smallexample
  83 (_GDBP__) help status
  84 Status inquiries.
  85
  86 List of commands:
  87
  88 show -- Generic command for showing things set with "set"
  89 info -- Generic command for printing status
  90
  91 Type "help" followed by command name for full documentation.
  92 Command name abbreviations are allowed if unambiguous.
  93 (_GDBP__)
  94 @end smallexample
  95
  96 @item help @var{command}
  97 With a command name as @code{help} argument, _GDBN__ will display a
  98 short paragraph on how to use that command.
  99 @end table
 100
 101 In addition to @code{help}, you can use the _GDBN__ commands @code{info}
 102 and @code{show} to inquire about the state of your program, or the state
 103 of _GDBN__ itself.  Both commands support many topics of inquiry; this
 104 manual introduces each of them in the appropriate context.  The listings
 105 under @code{info} and under @code{show} in the Index point to
 106 all the sub-commands.
 107 @c FIXME: @pxref{Index} used to be here, but even though it shows up in
 108 @c FIXME...the 'aux' file with a pageno the xref can't find it.
 109
 110 @c @group
 111 @table @code
 112 @item info
 113 @kindex info
 114 @kindex i
 115 This command (abbreviated @code{i}) is for describing the state of your
 116 program; for example, it can list the arguments given to your program
 117 (@code{info args}), the registers currently in use (@code{info
 118 registers}), or the breakpoints you've set (@code{info breakpoints}).
 119 You can get a complete list of the @code{info} sub-commands with
 120 @w{@code{help info}}.
 121
 122 @kindex show
 123 @item show
 124 In contrast, @code{show} is for describing the state of _GDBN__ itself.
 125 You can change most of the things you can @code{show}, by using the
 126 related command @code{set}; for example, you can control what number
 127 system is used for displays with @code{set radix}, or simply inquire
 128 which is currently in use with @code{show radix}.
 129
 130 @kindex info set
 131 To display all the settable parameters and their current
 132 values, you can use @code{show} with no arguments; you may also use
 133 @code{info set}.  Both commands produce the same display.
 134 @c FIXME: "info set" violates the rule that "info" is for state of
 135 @c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
 136 @c FIXME...or change desc of rule---eg "state of prog and debugging session"?
 137 @end table
 138 @c @end group
 139
 140 Here are three miscellaneous @code{show} subcommands, all of which are
 141 exceptional in lacking corresponding @code{set} commands:
 142
 143 @table @code
 144 @kindex show version
 145 @item show version
 146 Show what version of _GDBN__ is running.  You should include this
 147 information in _GDBN__ bug-reports.  If multiple versions of _GDBN__ are
 148 in use at your site, you may occasionally want to make sure what version
 149 of _GDBN__ you're running; as _GDBN__ evolves, new commands are
 150 introduced, and old ones may wither away.  The version number is also
 151 announced when you start _GDBN__ with no arguments.
 152
 153 @kindex show copying
 154 @item show copying
 155 Display information about permission for copying _GDBN__.
 156
 157 @kindex show warranty
 158 @item show warranty
 159 Display the GNU ``NO WARRANTY'' statement.
 160 @end table