178 lines
6.5 KiB
Text
Executable file
178 lines
6.5 KiB
Text
Executable file
_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
|