1 files changed, 178 insertions, 0 deletions
diff --git a/gdb/doc/gdb.canned-m4 b/gdb/doc/gdb.canned-m4
new file mode 100755
index 0000000..dc5b7b6
--- /dev/null
+++ b/gdb/doc/gdb.canned-m4
@@ -0,0 +1,178 @@
+_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
+_dnl__ This file is part of the source for the GDB manual.
+_dnl__ $Id$
+@node Sequences, Emacs, Controlling _GDBN__, Top
+@chapter Canned Sequences of Commands
+
+Aside from breakpoint commands (@pxref{Break Commands}), _GDBN__ provides two
+ways to store sequences of commands for execution as a unit:
+user-defined commands and command files.
+
+@menu
+* Define::			User-Defined Commands
+* Command Files::		Command Files
+* Output::			Commands for Controlled Output
+@end menu
+
+@node Define, Command Files, Sequences, Sequences
+@section User-Defined Commands
+
+@cindex user-defined command
+A @dfn{user-defined command} is a sequence of _GDBN__ commands to which you
+assign a new name as a command.  This is done with the @code{define}
+command.
+
+@table @code
+@item define @var{commandname}
+@kindex define
+Define a command named @var{commandname}.  If there is already a command
+by that name, you are asked to confirm that you want to redefine it.
+
+The definition of the command is made up of other _GDBN__ command lines,
+which are given following the @code{define} command.  The end of these
+commands is marked by a line containing @code{end}.
+
+@item document @var{commandname}
+@kindex document
+Give documentation to the user-defined command @var{commandname}.  The
+command @var{commandname} must already be defined.  This command reads
+lines of documentation just as @code{define} reads the lines of the
+command definition, ending with @code{end}.  After the @code{document}
+command is finished, @code{help} on command @var{commandname} will print
+the documentation you have specified.
+
+You may use the @code{document} command again to change the
+documentation of a command.  Redefining the command with @code{define}
+does not change the documentation.
+
+@item help user-defined
+@kindex help user-defined
+List all user-defined commands, with the first line of the documentation
+(if any) for each.
+
+@item info user
+@itemx info user @var{commandname}
+@kindex info user
+Display the _GDBN__ commands used to define @var{commandname} (but not its
+documentation).  If no @var{commandname} is given, display the
+definitions for all user-defined commands.
+@end table
+
+User-defined commands do not take arguments.  When they are executed, the
+commands of the definition are not printed.  An error in any command
+stops execution of the user-defined command.
+
+Commands that would ask for confirmation if used interactively proceed
+without asking when used inside a user-defined command.  Many _GDBN__ commands
+that normally print messages to say what they are doing omit the messages
+when used in a user-defined command.
+
+@node Command Files, Output, Define, Sequences
+@section Command Files
+
+@cindex command files
+A command file for _GDBN__ is a file of lines that are _GDBN__ commands.  Comments
+(lines starting with @kbd{#}) may also be included.  An empty line in a
+command file does nothing; it does not mean to repeat the last command, as
+it would from the terminal.
+
+@cindex init file
+@cindex @file{_GDBINIT__}
+When you start _GDBN__, it automatically executes commands from its
+@dfn{init files}.  These are files named @file{_GDBINIT__}.  _GDBN__
+reads the init file (if any) in your home directory and then the init
+file (if any) in the current working directory.  (The init files are not
+executed if you use the @samp{-nx} option; @pxref{Mode Options}.)  You
+can also request the execution of a command file with the @code{source}
+command:
+
+@table @code
+@item source @var{filename}
+@kindex source
+Execute the command file @var{filename}.
+@end table
+
+The lines in a command file are executed sequentially.  They are not
+printed as they are executed.  An error in any command terminates execution
+of the command file.
+
+Commands that would ask for confirmation if used interactively proceed
+without asking when used in a command file.  Many _GDBN__ commands that
+normally print messages to say what they are doing omit the messages
+when called from command files.
+
+@node Output,  , Command Files, Sequences
+@section Commands for Controlled Output
+
+During the execution of a command file or a user-defined command, normal
+_GDBN__ output is suppressed; the only output that appears is what is
+explicitly printed by the commands in the definition.  This section
+describes three commands useful for generating exactly the output you
+want.
+
+@table @code
+@item echo @var{text}
+@kindex echo
+@c I don't consider backslash-space a standard C escape sequence
+@c because it's not in ANSI.
+Print @var{text}.  Nonprinting characters can be included in @var{text}
+using C escape sequences, such as @samp{\n} to print a newline.  @b{No
+newline will be printed unless you specify one.} In addition to the
+standard C escape sequences, a backslash followed by a space stands for a
+space.  This is useful for outputting a string with spaces at the
+beginning or the end, since leading and trailing spaces are otherwise
+trimmed from all arguments.  Thus, to print @samp{@ and foo =@ }, use the
+command @samp{echo \@ and foo = \@ }.
+@c FIXME: verify hard copy actually issues enspaces for '@ '!  Will this
+@c        confuse texinfo?
+
+A backslash at the end of @var{text} can be used, as in C, to continue
+the command onto subsequent lines.  For example,
+
+@example
+echo This is some text\n\
+which is continued\n\
+onto several lines.\n
+@end example
+
+produces the same output as
+
+@example
+echo This is some text\n
+echo which is continued\n
+echo onto several lines.\n
+@end example
+
+@item output @var{expression}
+@kindex output
+Print the value of @var{expression} and nothing but that value: no
+newlines, no @samp{$@var{nn} = }.  The value is not entered in the
+value history either.  @xref{Expressions} for more information on
+expressions. 
+
+@item output/@var{fmt} @var{expression}
+Print the value of @var{expression} in format @var{fmt}.  You can use
+the same formats as for @code{print}; @pxref{Output formats}, for more
+information.
+
+@item printf @var{string}, @var{expressions}@dots{}
+@kindex printf
+Print the values of the @var{expressions} under the control of
+@var{string}.  The @var{expressions} are separated by commas and may
+be either numbers or pointers.  Their values are printed as specified
+by @var{string}, exactly as if the program were to execute
+
+@example
+printf (@var{string}, @var{expressions}@dots{});
+@end example
+
+For example, you can print two values in hex like this:
+
+@example
+printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
+@end example
+
+The only backslash-escape sequences that you can use in the format
+string are the simple ones that consist of backslash followed by a
+letter.
+@end table