gdb/doc/gdb.canned-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 Sequences, Emacs, Controlling _GDBN__, Top
   5 @chapter Canned Sequences of Commands
   6
   7 Aside from breakpoint commands (@pxref{Break Commands}), _GDBN__ provides two
   8 ways to store sequences of commands for execution as a unit:
   9 user-defined commands and command files.
  10
  11 @menu
  12 * Define::                      User-Defined Commands
  13 * Command Files::               Command Files
  14 * Output::                      Commands for Controlled Output
  15 @end menu
  16
  17 @node Define, Command Files, Sequences, Sequences
  18 @section User-Defined Commands
  19
  20 @cindex user-defined command
  21 A @dfn{user-defined command} is a sequence of _GDBN__ commands to which you
  22 assign a new name as a command.  This is done with the @code{define}
  23 command.
  24
  25 @table @code
  26 @item define @var{commandname}
  27 @kindex define
  28 Define a command named @var{commandname}.  If there is already a command
  29 by that name, you are asked to confirm that you want to redefine it.
  30
  31 The definition of the command is made up of other _GDBN__ command lines,
  32 which are given following the @code{define} command.  The end of these
  33 commands is marked by a line containing @code{end}.
  34
  35 @item document @var{commandname}
  36 @kindex document
  37 Give documentation to the user-defined command @var{commandname}.  The
  38 command @var{commandname} must already be defined.  This command reads
  39 lines of documentation just as @code{define} reads the lines of the
  40 command definition, ending with @code{end}.  After the @code{document}
  41 command is finished, @code{help} on command @var{commandname} will print
  42 the documentation you have specified.
  43
  44 You may use the @code{document} command again to change the
  45 documentation of a command.  Redefining the command with @code{define}
  46 does not change the documentation.
  47
  48 @item help user-defined
  49 @kindex help user-defined
  50 List all user-defined commands, with the first line of the documentation
  51 (if any) for each.
  52
  53 @item info user
  54 @itemx info user @var{commandname}
  55 @kindex info user
  56 Display the _GDBN__ commands used to define @var{commandname} (but not its
  57 documentation).  If no @var{commandname} is given, display the
  58 definitions for all user-defined commands.
  59 @end table
  60
  61 User-defined commands do not take arguments.  When they are executed, the
  62 commands of the definition are not printed.  An error in any command
  63 stops execution of the user-defined command.
  64
  65 Commands that would ask for confirmation if used interactively proceed
  66 without asking when used inside a user-defined command.  Many _GDBN__ commands
  67 that normally print messages to say what they are doing omit the messages
  68 when used in a user-defined command.
  69
  70 @node Command Files, Output, Define, Sequences
  71 @section Command Files
  72
  73 @cindex command files
  74 A command file for _GDBN__ is a file of lines that are _GDBN__ commands.  Comments
  75 (lines starting with @kbd{#}) may also be included.  An empty line in a
  76 command file does nothing; it does not mean to repeat the last command, as
  77 it would from the terminal.
  78
  79 @cindex init file
  80 @cindex @file{_GDBINIT__}
  81 When you start _GDBN__, it automatically executes commands from its
  82 @dfn{init files}.  These are files named @file{_GDBINIT__}.  _GDBN__
  83 reads the init file (if any) in your home directory and then the init
  84 file (if any) in the current working directory.  (The init files are not
  85 executed if you use the @samp{-nx} option; @pxref{Mode Options}.)  You
  86 can also request the execution of a command file with the @code{source}
  87 command:
  88
  89 @table @code
  90 @item source @var{filename}
  91 @kindex source
  92 Execute the command file @var{filename}.
  93 @end table
  94
  95 The lines in a command file are executed sequentially.  They are not
  96 printed as they are executed.  An error in any command terminates execution
  97 of the command file.
  98
  99 Commands that would ask for confirmation if used interactively proceed
 100 without asking when used in a command file.  Many _GDBN__ commands that
 101 normally print messages to say what they are doing omit the messages
 102 when called from command files.
 103
 104 @node Output,  , Command Files, Sequences
 105 @section Commands for Controlled Output
 106
 107 During the execution of a command file or a user-defined command, normal
 108 _GDBN__ output is suppressed; the only output that appears is what is
 109 explicitly printed by the commands in the definition.  This section
 110 describes three commands useful for generating exactly the output you
 111 want.
 112
 113 @table @code
 114 @item echo @var{text}
 115 @kindex echo
 116 @c I don't consider backslash-space a standard C escape sequence
 117 @c because it's not in ANSI.
 118 Print @var{text}.  Nonprinting characters can be included in @var{text}
 119 using C escape sequences, such as @samp{\n} to print a newline.  @b{No
 120 newline will be printed unless you specify one.} In addition to the
 121 standard C escape sequences, a backslash followed by a space stands for a
 122 space.  This is useful for outputting a string with spaces at the
 123 beginning or the end, since leading and trailing spaces are otherwise
 124 trimmed from all arguments.  Thus, to print @samp{@ and foo =@ }, use the
 125 command @samp{echo \@ and foo = \@ }.
 126 @c FIXME: verify hard copy actually issues enspaces for '@ '!  Will this
 127 @c        confuse texinfo?
 128
 129 A backslash at the end of @var{text} can be used, as in C, to continue
 130 the command onto subsequent lines.  For example,
 131
 132 @example
 133 echo This is some text\n\
 134 which is continued\n\
 135 onto several lines.\n
 136 @end example
 137
 138 produces the same output as
 139
 140 @example
 141 echo This is some text\n
 142 echo which is continued\n
 143 echo onto several lines.\n
 144 @end example
 145
 146 @item output @var{expression}
 147 @kindex output
 148 Print the value of @var{expression} and nothing but that value: no
 149 newlines, no @samp{$@var{nn} = }.  The value is not entered in the
 150 value history either.  @xref{Expressions} for more information on
 151 expressions.
 152
 153 @item output/@var{fmt} @var{expression}
 154 Print the value of @var{expression} in format @var{fmt}.  You can use
 155 the same formats as for @code{print}; @pxref{Output formats}, for more
 156 information.
 157
 158 @item printf @var{string}, @var{expressions}@dots{}
 159 @kindex printf
 160 Print the values of the @var{expressions} under the control of
 161 @var{string}.  The @var{expressions} are separated by commas and may
 162 be either numbers or pointers.  Their values are printed as specified
 163 by @var{string}, exactly as if the program were to execute
 164
 165 @example
 166 printf (@var{string}, @var{expressions}@dots{});
 167 @end example
 168
 169 For example, you can print two values in hex like this:
 170
 171 @example
 172 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
 173 @end example
 174
 175 The only backslash-escape sequences that you can use in the format
 176 string are the simple ones that consist of backslash followed by a
 177 letter.
 178 @end table