binutils-gdb/gdb/doc/gdb.canned-m4

_dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
_dnl__ This file is part of the source for the GDB manual.
@c M4 FRAGMENT: $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