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.
4 @node Sequences, Emacs, Controlling _GDBN__, Top
5 @chapter Canned Sequences of Commands
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.
12 * Define:: User-Defined Commands
13 * Command Files:: Command Files
14 * Output:: Commands for Controlled Output
17 @node Define, Command Files, Sequences, Sequences
18 @section User-Defined Commands
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}
26 @item define @var{commandname}
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.
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}.
35 @item document @var{commandname}
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.
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.
48 @item help user-defined
49 @kindex help user-defined
50 List all user-defined commands, with the first line of the documentation
54 @itemx info user @var{commandname}
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.
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.
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.
70 @node Command Files, Output, Define, Sequences
71 @section 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.
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}
90 @item source @var{filename}
92 Execute the command file @var{filename}.
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
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.
104 @node Output, , Command Files, Sequences
105 @section Commands for Controlled Output
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
114 @item echo @var{text}
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
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,
133 echo This is some text\n\
134 which is continued\n\
135 onto several lines.\n
138 produces the same output as
141 echo This is some text\n
142 echo which is continued\n
143 echo onto several lines.\n
146 @item output @var{expression}
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
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
158 @item printf @var{string}, @var{expressions}@dots{}
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
166 printf (@var{string}, @var{expressions}@dots{});
169 For example, you can print two values in hex like this:
172 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
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