gdb/doc/gdb.sample-m4

   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