2 _dnl__ Copyright (c) 1991 Free Software Foundation, Inc.
3 _dnl__ This file is part of the source for the GDB manual.
5 @node Sample Session, Invocation, New Features, Top
6 @chapter A Sample _GDBN__ Session
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.
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.
17 @c FIXME: this example may not be appropriate for some configs, where
18 @c FIXME...primary interest is in remote use.
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}:
37 @i{define(bar,defn(`foo'))}
41 @i{changequote(<QUOTE>,<UNQUOTE>)}
43 @i{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
46 m4: End of input: 0: fatal error: EOF in string
50 Let's use _GDBN__ to try to see what's going on.
54 Reading symbol data from m4...done.
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.
65 (_GDBP__) @i{set width 70}
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
75 (_GDBP__) @i{break m4_changequote}
76 Breakpoint 1 at 0x62f4: file builtin.c, line 879.
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:
86 Starting program: /work/Editorial/gdb/gnu/m4/m4
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.
99 @i{changequote(<QUOTE>,<UNQUOTE>)}
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))
106 Now we use the command @code{n} (@code{next}) to advance execution to
107 the next line of the current function.
111 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1]) : nil,
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}.
122 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
124 530 if (lquote != def_lquote)
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
136 #0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
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)
142 #4 0x79dc in expand_input () at macro.c:40
143 #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195
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.
152 0x3b5c 532 if (rquote != def_rquote)
154 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? def_lquote :\
157 536 rquote = (rq == nil || *rq == '\0') ? def_rquote : xstrdup\
160 538 len_lquote = strlen(rquote);
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.
170 (_GDBP__) @i{p lquote}
171 $1 = 0x35d40 "<QUOTE>"
172 (_GDBP__) @i{p rquote}
173 $2 = 0x35d50 "<UNQUOTE>"
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.
185 535 lquote = (lq == nil || *lq == '\0') ? def_lquote : xstrdup\
187 536 rquote = (rq == nil || *rq == '\0') ? def_rquote : xstrdup\
190 538 len_lquote = strlen(rquote);
191 539 len_rquote = strlen(lquote);
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.
203 539 len_rquote = strlen(lquote);
206 (_GDBP__) @i{p len_lquote}
208 (_GDBP__) @i{p len_rquote}
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
221 (_GDBP__) p len_lquote=strlen(lquote)
223 (_GDBP__) p len_rquote=strlen(rquote)
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:
237 @i{define(baz,defn(<QUOTE>foo<UNQUOTE>))}
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.
250 Program exited normally.
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.
262 _1__@end smallexample