Commit | Line | Data |
---|---|---|
9bcc06ef RP |
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. | |
16e58d91 | 3 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
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 |