Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ -*- Texinfo -*- |
2 | _dnl__ Copyright (c) 1991 Free Software Foundation, Inc. | |
3 | _dnl__ This file is part of the source for the GDB manual. | |
4 | _dnl__ $Id$ | |
5 | @node Sample Session, Invocation, New Features, Top | |
6 | @chapter A Sample _GDBN__ Session | |
7 | ||
8 | You can use this manual at your leisure to read all about _GDBN__. | |
9 | However, a handful of commands are enough to get started using the | |
10 | debugger. This chapter illustrates these commands. | |
11 | ||
12 | @iftex | |
13 | In this sample session, we emphasize user input like this: @i{input}, | |
14 | to make it easier to pick out from the surrounding output. | |
15 | @end iftex | |
16 | ||
17 | @c FIXME: this example may not be appropriate for some configs, where | |
18 | @c FIXME...primary interest is in remote use. | |
19 | _0__ | |
20 | One of the preliminary versions of GNU @code{m4} (a generic macro | |
21 | processor) exhibits the following bug: sometimes, when we change its | |
22 | quote strings from the default, the commands used to capture one macro's | |
23 | definition in another stop working. In the following short @code{m4} | |
24 | session, we define a macro @code{foo} which expands to @code{0000}; we | |
25 | then use the @code{m4} builtin @code{defn} to define @code{bar} as the | |
26 | same thing. However, when we change the open quote string to | |
27 | @code{<QUOTE>} and the close quote string to @code{<UNQUOTE>}, the same | |
28 | procedure fails to define a new synonym @code{baz}: | |
29 | ||
30 | @smallexample | |
31 | $ @i{cd gnu/m4} | |
32 | $ @i{./m4} | |
33 | @i{define(foo,0000)} | |
34 | ||
35 | @i{foo} | |
36 | 0000 | |
37 | @i{define(bar,defn(`foo'))} | |
38 | ||
39 | @i{bar} | |
40 | 0000 | |
41 | @i{changequote(<QUOTE>,<UNQUOTE>)} | |
42 | ||
43 | @i{define(baz,defn(<QUOTE>foo<UNQUOTE>))} | |
44 | @i{baz} | |
45 | @i{C-D} | |
46 | m4: End of input: 0: fatal error: EOF in string | |
47 | @end smallexample | |
48 | ||
49 | @noindent | |
50 | Let's use _GDBN__ to try to see what's going on. | |
51 | ||
52 | @smallexample | |
53 | $ @i{_GDBP__ m4} | |
54 | Reading symbol data from m4...done. | |
55 | (_GDBP__) | |
56 | @end smallexample | |
57 | ||
58 | @noindent | |
59 | _GDBN__ only reads enough symbol data to know where to find the rest | |
60 | when needed; as a result, the first prompt comes up very quickly. We | |
61 | then tell _GDBN__ to use a narrower display width than usual, so | |
62 | that examples will fit in this manual. | |
63 | ||
64 | @smallexample | |
65 | (_GDBP__) @i{set width 70} | |
66 | @end smallexample | |
67 | ||
68 | @noindent | |
69 | Let's see how the @code{m4} builtin @code{changequote} works. | |
70 | Having looked at the source, we know the relevant subroutine is | |
71 | @code{m4_changequote}, so we set a breakpoint there with _GDBN__'s | |
72 | @code{break} command. | |
73 | ||
74 | @smallexample | |
75 | (_GDBP__) @i{break m4_changequote} | |
76 | Breakpoint 1 at 0x62f4: file builtin.c, line 879. | |
77 | @end smallexample | |
78 | ||
79 | @noindent | |
80 | Using the @code{run} command, we start @code{m4} running under _GDBN__ | |
81 | control; as long as control does not reach the @code{m4_changequote} | |
82 | subroutine, the program runs as usual: | |
83 | ||
84 | @smallexample | |
85 | (_GDBP__) @i{run} | |
86 | Starting program: /work/Editorial/gdb/gnu/m4/m4 | |
87 | @i{define(foo,0000)} | |
88 | ||
89 | @i{foo} | |
90 | 0000 | |
91 | @end smallexample | |
92 | ||
93 | @noindent | |
94 | To trigger the breakpoint, we call @code{changequote}. _GDBN__ | |
95 | suspends execution of @code{m4}, displaying information about the | |
96 | context where it stops. | |
97 | ||
98 | @smallexample | |
99 | @i{changequote(<QUOTE>,<UNQUOTE>)} | |
100 | ||
101 | Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) at builtin.c:879 | |
102 | 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]), argc, 1, 3)) | |
103 | @end smallexample | |
104 | ||
105 | @noindent | |
106 | Now we use the command @code{n} (@code{next}) to advance execution to | |
107 | the next line of the current function. | |
108 | ||
109 | @smallexample | |
110 | (_GDBP__) @i{n} | |
111 | 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1]) : nil, | |
112 | @end smallexample | |
113 | ||
114 | @noindent | |
115 | @code{set_quotes} looks like a promising subroutine. We can go into it | |
116 | by using the command @code{s} (@code{step}) instead of @code{next}. | |
117 | @code{step} goes to the next line to be executed in @emph{any} | |
118 | subroutine, so it steps into @code{set_quotes}. | |
119 | ||
120 | @smallexample | |
121 | (_GDBP__) @i{s} | |
122 | set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") | |
123 | at input.c:530 | |
124 | 530 if (lquote != def_lquote) | |
125 | @end smallexample | |
126 | ||
127 | @noindent | |
128 | The summary display showing the subroutine where @code{m4} is now | |
129 | suspended (and its arguments) is called a stack frame display. We can | |
130 | use the @code{backtrace} command (which can also be spelled @code{bt}), | |
131 | to see where we are in the stack: it displays a stack frame for each | |
132 | active subroutine. | |
133 | ||
134 | @smallexample | |
135 | (_GDBP__) @i{bt} | |
136 | #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") | |
137 | at input.c:530 | |
138 | #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) at builtin.c:882 | |
139 | #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 | |
140 | #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) | |
141 | at macro.c:71 | |
142 | #4 0x79dc in expand_input () at macro.c:40 | |
143 | #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 | |
144 | @end smallexample | |
145 | ||
146 | @noindent | |
147 | Let's step through a few more lines to see what happens. The first two | |
148 | times, we can use @samp{s}; the next two times we use @code{n} to avoid | |
149 | falling into the @code{xstrdup} subroutine. | |
150 | @smallexample | |
151 | (_GDBP__) @i{s} | |
152 | 0x3b5c 532 if (rquote != def_rquote) | |
153 | (_GDBP__) @i{s} | |
154 | 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? def_lquote :\ | |
155 | xstrdup(lq); | |
156 | (_GDBP__) @i{n} | |
157 | 536 rquote = (rq == nil || *rq == '\0') ? def_rquote : xstrdup\ | |
158 | (rq); | |
159 | (_GDBP__) @i{n} | |
160 | 538 len_lquote = strlen(rquote); | |
161 | @end smallexample | |
162 | ||
163 | @noindent | |
164 | The last line displayed looks a little odd; let's examine the variables | |
165 | @code{lquote} and @code{rquote} to see if they are in fact the new left | |
166 | and right quotes we specified. We can use the command @code{p} | |
167 | (@code{print}) to see their values. | |
168 | ||
169 | @smallexample | |
170 | (_GDBP__) @i{p lquote} | |
171 | $1 = 0x35d40 "<QUOTE>" | |
172 | (_GDBP__) @i{p rquote} | |
173 | $2 = 0x35d50 "<UNQUOTE>" | |
174 | @end smallexample | |
175 | ||
176 | @noindent | |
177 | @code{lquote} and @code{rquote} are indeed the new left and right quotes. | |
178 | Let's look at some context; we can display ten lines of source | |
179 | surrounding the current line, with the @code{l} (@code{list}) command. | |
180 | ||
181 | @smallexample | |
182 | (_GDBP__) @i{l} | |
183 | 533 xfree(rquote); | |
184 | 534 | |
185 | 535 lquote = (lq == nil || *lq == '\0') ? def_lquote : xstrdup\ | |
186 | (lq); | |
187 | 536 rquote = (rq == nil || *rq == '\0') ? def_rquote : xstrdup\ | |
188 | (rq); | |
189 | 537 | |
190 | 538 len_lquote = strlen(rquote); | |
191 | 539 len_rquote = strlen(lquote); | |
192 | 540 @} | |
193 | 541 | |
194 | 542 void | |
195 | @end smallexample | |
196 | ||
197 | @noindent | |
198 | Let's step past the two lines that set @code{len_lquote} and | |
199 | @code{len_rquote}, and then examine the values of those variables. | |
200 | ||
201 | @smallexample | |
202 | (_GDBP__) @i{n} | |
203 | 539 len_rquote = strlen(lquote); | |
204 | (_GDBP__) @i{n} | |
205 | 540 @} | |
206 | (_GDBP__) @i{p len_lquote} | |
207 | $3 = 9 | |
208 | (_GDBP__) @i{p len_rquote} | |
209 | $4 = 7 | |
210 | @end smallexample | |
211 | ||
212 | @noindent | |
213 | That certainly looks wrong, assuming @code{len_lquote} and | |
214 | @code{len_rquote} are meant to be the lengths of @code{lquote} and | |
215 | @code{rquote} respectively. Let's try setting them to better values. | |
216 | We can use the @code{p} command for this, since it'll print the value of | |
217 | any expression---and that expression can include subroutine calls and | |
218 | assignments. | |
219 | ||
220 | @smallexample | |
221 | (_GDBP__) p len_lquote=strlen(lquote) | |
222 | $5 = 7 | |
223 | (_GDBP__) p len_rquote=strlen(rquote) | |
224 | $6 = 9 | |
225 | @end smallexample | |
226 | ||
227 | @noindent | |
228 | Let's see if that fixes the problem of using the new quotes with the | |
229 | @code{m4} built-in @code{defn}. We can allow @code{m4} to continue | |
230 | executing with the @code{c} (@code{continue}) command, and then try the | |
231 | example that caused trouble initially: | |
232 | ||
233 | @smallexample | |
234 | (_GDBP__) @i{c} | |
235 | Continuing. | |
236 | ||
237 | @i{define(baz,defn(<QUOTE>foo<UNQUOTE>))} | |
238 | ||
239 | baz | |
240 | 0000 | |
241 | @end smallexample | |
242 | ||
243 | @noindent | |
244 | Success! The new quotes now work just as well as the default ones. The | |
245 | problem seems to have been just the two typos defining the wrong | |
246 | lengths. We'll let @code{m4} exit by giving it an EOF as input. | |
247 | ||
248 | @smallexample | |
249 | @i{C-D} | |
250 | Program exited normally. | |
251 | @end smallexample | |
252 | ||
253 | @noindent | |
254 | The message @samp{Program exited normally.} is from _GDBN__; it | |
255 | indicates @code{m4} has finished executing. We can end our _GDBN__ | |
256 | session with the _GDBN__ @code{quit} command. | |
257 | ||
258 | @smallexample | |
259 | (_GDBP__) @i{quit} | |
260 | ||
261 | $ | |
262 | _1__@end smallexample | |
263 |