"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/debugging_with_gdb.html" (9 Sep 2020, 17147 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <!--{
    2     "Title": "Debugging Go Code with GDB",
    3     "Path": "/doc/gdb"
    4 }-->
    5 
    6 <!--
    7 NOTE: In this document and others in this directory, the convention is to
    8 set fixed-width phrases with non-fixed-width spaces, as in
    9 <code>hello</code> <code>world</code>.
   10 Do not send CLs removing the interior tags from such phrases.
   11 -->
   12 
   13 <i>
   14 <p>
   15 The following instructions apply to the standard toolchain
   16 (the <code>gc</code> Go compiler and tools).
   17 Gccgo has native gdb support.
   18 </p>
   19 <p>
   20 Note that 
   21 <a href="https://github.com/derekparker/delve">Delve</a> is a better 
   22 alternative to GDB when debugging Go programs built with the standard
   23 toolchain. It understands the Go runtime, data structures, and
   24 expressions better than GDB. Delve currently supports Linux, OSX,
   25 and Windows on <code>amd64</code>.
   26 For the most up-to-date list of supported platforms, please see
   27 <a href="https://github.com/derekparker/delve/tree/master/Documentation/installation">
   28  the Delve documentation</a>.
   29 </p>
   30 </i>
   31 
   32 <p>
   33 GDB does not understand Go programs well.
   34 The stack management, threading, and runtime contain aspects that differ
   35 enough from the execution model GDB expects that they can confuse
   36 the debugger and cause incorrect results even when the program is
   37 compiled with gccgo.
   38 As a consequence, although GDB can be useful in some situations (e.g.,
   39 debugging Cgo code, or debugging the runtime itself), it is not
   40 a reliable debugger for Go programs, particularly heavily concurrent
   41 ones.  Moreover, it is not a priority for the Go project to address
   42 these issues, which are difficult.
   43 </p>
   44 
   45 <p>
   46 In short, the instructions below should be taken only as a guide to how
   47 to use GDB when it works, not as a guarantee of success.
   48 
   49 Besides this overview you might want to consult the
   50 <a href="https://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
   51 </p>
   52 
   53 <p>
   54 </p>
   55 
   56 <h2 id="Introduction">Introduction</h2>
   57 
   58 <p>
   59 When you compile and link your Go programs with the <code>gc</code> toolchain
   60 on Linux, macOS, FreeBSD or NetBSD, the resulting binaries contain DWARFv4
   61 debugging information that recent versions (&ge;7.5) of the GDB debugger can
   62 use to inspect a live process or a core dump.
   63 </p>
   64 
   65 <p>
   66 Pass the <code>'-w'</code> flag to the linker to omit the debug information
   67 (for example, <code>go</code> <code>build</code> <code>-ldflags=-w</code> <code>prog.go</code>).
   68 </p>
   69 
   70 <p>
   71 The code generated by the <code>gc</code> compiler includes inlining of
   72 function invocations and registerization of variables. These optimizations
   73 can sometimes make debugging with <code>gdb</code> harder.
   74 If you find that you need to disable these optimizations,
   75 build your program using <code>go</code> <code>build</code> <code>-gcflags=all="-N -l"</code>.
   76 </p>
   77 
   78 <p>
   79 If you want to use gdb to inspect a core dump, you can trigger a dump
   80 on a program crash, on systems that permit it, by setting
   81 <code>GOTRACEBACK=crash</code> in the environment (see the
   82 <a href="/pkg/runtime/#hdr-Environment_Variables"> runtime package
   83 documentation</a> for more info).
   84 </p>
   85 
   86 <h3 id="Common_Operations">Common Operations</h3>
   87 
   88 <ul>
   89 <li>
   90 Show file and line number for code, set breakpoints and disassemble:
   91 <pre>(gdb) <b>list</b>
   92 (gdb) <b>list <i>line</i></b>
   93 (gdb) <b>list <i>file.go</i>:<i>line</i></b>
   94 (gdb) <b>break <i>line</i></b>
   95 (gdb) <b>break <i>file.go</i>:<i>line</i></b>
   96 (gdb) <b>disas</b></pre>
   97 </li>
   98 <li>
   99 Show backtraces and unwind stack frames:
  100 <pre>(gdb) <b>bt</b>
  101 (gdb) <b>frame <i>n</i></b></pre>
  102 </li>
  103 <li>
  104 Show the name, type and location on the stack frame of local variables,
  105 arguments and return values:
  106 <pre>(gdb) <b>info locals</b>
  107 (gdb) <b>info args</b>
  108 (gdb) <b>p variable</b>
  109 (gdb) <b>whatis variable</b></pre>
  110 </li>
  111 <li>
  112 Show the name, type and location of global variables:
  113 <pre>(gdb) <b>info variables <i>regexp</i></b></pre>
  114 </li>
  115 </ul>
  116 
  117 
  118 <h3 id="Go_Extensions">Go Extensions</h3>
  119 
  120 <p>
  121 A recent extension mechanism to GDB allows it to load extension scripts for a
  122 given binary. The toolchain uses this to extend GDB with a handful of
  123 commands to inspect internals of the runtime code (such as goroutines) and to
  124 pretty print the built-in map, slice and channel types.
  125 </p>
  126 
  127 <ul>
  128 <li>
  129 Pretty printing a string, slice, map, channel or interface:
  130 <pre>(gdb) <b>p <i>var</i></b></pre>
  131 </li>
  132 <li>
  133 A $len() and $cap() function for strings, slices and maps:
  134 <pre>(gdb) <b>p $len(<i>var</i>)</b></pre>
  135 </li>
  136 <li>
  137 A function to cast interfaces to their dynamic types:
  138 <pre>(gdb) <b>p $dtype(<i>var</i>)</b>
  139 (gdb) <b>iface <i>var</i></b></pre>
  140 <p class="detail"><b>Known issue:</b> GDB can’t automatically find the dynamic
  141 type of an interface value if its long name differs from its short name
  142 (annoying when printing stacktraces, the pretty printer falls back to printing
  143 the short type name and a pointer).</p>
  144 </li>
  145 <li>
  146 Inspecting goroutines:
  147 <pre>(gdb) <b>info goroutines</b>
  148 (gdb) <b>goroutine <i>n</i> <i>cmd</i></b>
  149 (gdb) <b>help goroutine</b></pre>
  150 For example:
  151 <pre>(gdb) <b>goroutine 12 bt</b></pre>
  152 You can inspect all goroutines by passing <code>all</code> instead of a specific goroutine's ID.
  153 For example:
  154 <pre>(gdb) <b>goroutine all bt</b></pre>
  155 </li>
  156 </ul>
  157 
  158 <p>
  159 If you'd like to see how this works, or want to extend it, take a look at <a
  160 href="/src/runtime/runtime-gdb.py">src/runtime/runtime-gdb.py</a> in
  161 the Go source distribution. It depends on some special magic types
  162 (<code>hash&lt;T,U&gt;</code>) and variables (<code>runtime.m</code> and
  163 <code>runtime.g</code>) that the linker
  164 (<a href="/src/cmd/link/internal/ld/dwarf.go">src/cmd/link/internal/ld/dwarf.go</a>) ensures are described in
  165 the DWARF code.
  166 </p>
  167 
  168 <p>
  169 If you're interested in what the debugging information looks like, run
  170 <code>objdump</code> <code>-W</code> <code>a.out</code> and browse through the <code>.debug_*</code>
  171 sections.
  172 </p>
  173 
  174 
  175 <h3 id="Known_Issues">Known Issues</h3>
  176 
  177 <ol>
  178 <li>String pretty printing only triggers for type string, not for types derived
  179 from it.</li>
  180 <li>Type information is missing for the C parts of the runtime library.</li>
  181 <li>GDB does not understand Go’s name qualifications and treats
  182 <code>"fmt.Print"</code> as an unstructured literal with a <code>"."</code>
  183 that needs to be quoted.  It objects even more strongly to method names of
  184 the form <code>pkg.(*MyType).Meth</code>.
  185 <li>As of Go 1.11, debug information is compressed by default.
  186 Older versions of gdb, such as the one available by default on MacOS,
  187 do not understand the compression.
  188 You can generate uncompressed debug information by using <code>go
  189 build -ldflags=-compressdwarf=false</code>.
  190 (For convenience you can put the <code>-ldflags</code> option in
  191 the <a href="/cmd/go/#hdr-Environment_variables"><code>GOFLAGS</code>
  192 environment variable</a> so that you don't have to specify it each time.)
  193 </li>
  194 </ol>
  195 
  196 <h2 id="Tutorial">Tutorial</h2>
  197 
  198 <p>
  199 In this tutorial we will inspect the binary of the
  200 <a href="/pkg/regexp/">regexp</a> package's unit tests. To build the binary,
  201 change to <code>$GOROOT/src/regexp</code> and run <code>go</code> <code>test</code> <code>-c</code>.
  202 This should produce an executable file named <code>regexp.test</code>.
  203 </p>
  204 
  205 
  206 <h3 id="Getting_Started">Getting Started</h3>
  207 
  208 <p>
  209 Launch GDB, debugging <code>regexp.test</code>:
  210 </p>
  211 
  212 <pre>
  213 $ <b>gdb regexp.test</b>
  214 GNU gdb (GDB) 7.2-gg8
  215 Copyright (C) 2010 Free Software Foundation, Inc.
  216 License GPLv  3+: GNU GPL version 3 or later &lt;http://gnu.org/licenses/gpl.html&gt;
  217 Type "show copying" and "show warranty" for licensing/warranty details.
  218 This GDB was configured as "x86_64-linux".
  219 
  220 Reading symbols from  /home/user/go/src/regexp/regexp.test...
  221 done.
  222 Loading Go Runtime support.
  223 (gdb) 
  224 </pre>
  225 
  226 <p>
  227 The message "Loading Go Runtime support" means that GDB loaded the
  228 extension from <code>$GOROOT/src/runtime/runtime-gdb.py</code>.
  229 </p>
  230 
  231 <p>
  232 To help GDB find the Go runtime sources and the accompanying support script,
  233 pass your <code>$GOROOT</code> with the <code>'-d'</code> flag:
  234 </p>
  235 
  236 <pre>
  237 $ <b>gdb regexp.test -d $GOROOT</b>
  238 </pre>
  239 
  240 <p>
  241 If for some reason GDB still can't find that directory or that script, you can load
  242 it by hand by telling gdb (assuming you have the go sources in
  243 <code>~/go/</code>):
  244 </p>
  245 
  246 <pre>
  247 (gdb) <b>source ~/go/src/runtime/runtime-gdb.py</b>
  248 Loading Go Runtime support.
  249 </pre>
  250 
  251 <h3 id="Inspecting_the_source">Inspecting the source</h3>
  252 
  253 <p>
  254 Use the <code>"l"</code> or <code>"list"</code> command to inspect source code.
  255 </p>
  256 
  257 <pre>
  258 (gdb) <b>l</b>
  259 </pre>
  260 
  261 <p>
  262 List a specific part of the source parameterizing <code>"list"</code> with a
  263 function name (it must be qualified with its package name).
  264 </p>
  265 
  266 <pre>
  267 (gdb) <b>l main.main</b>
  268 </pre>
  269 
  270 <p>
  271 List a specific file and line number:
  272 </p>
  273 
  274 <pre>
  275 (gdb) <b>l regexp.go:1</b>
  276 (gdb) <i># Hit enter to repeat last command. Here, this lists next 10 lines.</i>
  277 </pre>
  278 
  279 
  280 <h3 id="Naming">Naming</h3>
  281 
  282 <p>
  283 Variable and function names must be qualified with the name of the packages
  284 they belong to. The <code>Compile</code> function from the <code>regexp</code>
  285 package is known to GDB as <code>'regexp.Compile'</code>. 
  286 </p>
  287 
  288 <p>
  289 Methods must be qualified with the name of their receiver types. For example,
  290 the <code>*Regexp</code> type’s <code>String</code> method is known as
  291 <code>'regexp.(*Regexp).String'</code>.
  292 </p>
  293 
  294 <p>
  295 Variables that shadow other variables are magically suffixed with a number in the debug info.
  296 Variables referenced by closures will appear as pointers magically prefixed with '&amp;'.
  297 </p>
  298 
  299 <h3 id="Setting_breakpoints">Setting breakpoints</h3>
  300 
  301 <p>
  302 Set a breakpoint at the <code>TestFind</code> function:
  303 </p>
  304 
  305 <pre>
  306 (gdb) <b>b 'regexp.TestFind'</b>
  307 Breakpoint 1 at 0x424908: file /home/user/go/src/regexp/find_test.go, line 148.
  308 </pre>
  309 
  310 <p>
  311 Run the program:
  312 </p>
  313 
  314 <pre>
  315 (gdb) <b>run</b>
  316 Starting program: /home/user/go/src/regexp/regexp.test
  317 
  318 Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148
  319 148 func TestFind(t *testing.T) {
  320 </pre>
  321 
  322 <p>
  323 Execution has paused at the breakpoint.
  324 See which goroutines are running, and what they're doing:
  325 </p>
  326 
  327 <pre>
  328 (gdb) <b>info goroutines</b>
  329   1  waiting runtime.gosched
  330 * 13  running runtime.goexit
  331 </pre>
  332 
  333 <p>
  334 the one marked with the <code>*</code> is the current goroutine.
  335 </p>
  336 
  337 <h3 id="Inspecting_the_stack">Inspecting the stack</h3>
  338 
  339 <p>
  340 Look at the stack trace for where we’ve paused the program:
  341 </p>
  342 
  343 <pre>
  344 (gdb) <b>bt</b>  <i># backtrace</i>
  345 #0  regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148
  346 #1  0x000000000042f60b in testing.tRunner (t=0xf8404a89c0, test=0x573720) at /home/user/go/src/testing/testing.go:156
  347 #2  0x000000000040df64 in runtime.initdone () at /home/user/go/src/runtime/proc.c:242
  348 #3  0x000000f8404a89c0 in ?? ()
  349 #4  0x0000000000573720 in ?? ()
  350 #5  0x0000000000000000 in ?? ()
  351 </pre>
  352 
  353 <p>
  354 The other goroutine, number 1, is stuck in <code>runtime.gosched</code>, blocked on a channel receive:
  355 </p>
  356 
  357 <pre>
  358 (gdb) <b>goroutine 1 bt</b>
  359 #0  0x000000000040facb in runtime.gosched () at /home/user/go/src/runtime/proc.c:873
  360 #1  0x00000000004031c9 in runtime.chanrecv (c=void, ep=void, selected=void, received=void)
  361  at  /home/user/go/src/runtime/chan.c:342
  362 #2  0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/runtime/chan.c:423
  363 #3  0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, error *)}
  364  0x7ffff7f9ef60, tests=  []testing.InternalTest = {...}) at /home/user/go/src/testing/testing.go:201
  365 #4  0x00000000004302b1 in testing.Main (matchString={void (struct string, struct string, bool *, error *)} 
  366  0x7ffff7f9ef80, tests= []testing.InternalTest = {...}, benchmarks= []testing.InternalBenchmark = {...})
  367 at /home/user/go/src/testing/testing.go:168
  368 #5  0x0000000000400dc1 in main.main () at /home/user/go/src/regexp/_testmain.go:98
  369 #6  0x00000000004022e7 in runtime.mainstart () at /home/user/go/src/runtime/amd64/asm.s:78
  370 #7  0x000000000040ea6f in runtime.initdone () at /home/user/go/src/runtime/proc.c:243
  371 #8  0x0000000000000000 in ?? ()
  372 </pre>
  373 
  374 <p>
  375 The stack frame shows we’re currently executing the <code>regexp.TestFind</code> function, as expected.
  376 </p>
  377 
  378 <pre>
  379 (gdb) <b>info frame</b>
  380 Stack level 0, frame at 0x7ffff7f9ff88:
  381  rip = 0x425530 in regexp.TestFind (/home/user/go/src/regexp/find_test.go:148); 
  382     saved rip 0x430233
  383  called by frame at 0x7ffff7f9ffa8
  384  source language minimal.
  385  Arglist at 0x7ffff7f9ff78, args: t=0xf840688b60
  386  Locals at 0x7ffff7f9ff78, Previous frame's sp is 0x7ffff7f9ff88
  387  Saved registers:
  388   rip at 0x7ffff7f9ff80
  389 </pre>
  390 
  391 <p>
  392 The command <code>info</code> <code>locals</code> lists all variables local to the function and their values, but is a bit
  393 dangerous to use, since it will also try to print uninitialized variables. Uninitialized slices may cause gdb to try
  394 to print arbitrary large arrays.
  395 </p>
  396 
  397 <p>
  398 The function’s arguments:
  399 </p>
  400 
  401 <pre>
  402 (gdb) <b>info args</b>
  403 t = 0xf840688b60
  404 </pre>
  405 
  406 <p>
  407 When printing the argument, notice that it’s a pointer to a
  408 <code>Regexp</code> value. Note that GDB has incorrectly put the <code>*</code>
  409 on the right-hand side of the type name and made up a 'struct' keyword, in traditional C style.
  410 </p>
  411 
  412 <pre>
  413 (gdb) <b>p re</b>
  414 (gdb) p t
  415 $1 = (struct testing.T *) 0xf840688b60
  416 (gdb) p t
  417 $1 = (struct testing.T *) 0xf840688b60
  418 (gdb) p *t
  419 $2 = {errors = "", failed = false, ch = 0xf8406f5690}
  420 (gdb) p *t-&gt;ch
  421 $3 = struct hchan&lt;*testing.T&gt;
  422 </pre>
  423 
  424 <p>
  425 That <code>struct</code> <code>hchan&lt;*testing.T&gt;</code> is the
  426 runtime-internal representation of a channel. It is currently empty,
  427 or gdb would have pretty-printed its contents.
  428 </p>
  429 
  430 <p>
  431 Stepping forward:
  432 </p>
  433 
  434 <pre>
  435 (gdb) <b>n</b>  <i># execute next line</i>
  436 149             for _, test := range findTests {
  437 (gdb)    <i># enter is repeat</i>
  438 150                     re := MustCompile(test.pat)
  439 (gdb) <b>p test.pat</b>
  440 $4 = ""
  441 (gdb) <b>p re</b>
  442 $5 = (struct regexp.Regexp *) 0xf84068d070
  443 (gdb) <b>p *re</b>
  444 $6 = {expr = "", prog = 0xf840688b80, prefix = "", prefixBytes =  []uint8, prefixComplete = true, 
  445   prefixRune = 0, cond = 0 '\000', numSubexp = 0, longest = false, mu = {state = 0, sema = 0}, 
  446   machine =  []*regexp.machine}
  447 (gdb) <b>p *re->prog</b>
  448 $7 = {Inst =  []regexp/syntax.Inst = {{Op = 5 '\005', Out = 0, Arg = 0, Rune =  []int}, {Op = 
  449     6 '\006', Out = 2, Arg = 0, Rune =  []int}, {Op = 4 '\004', Out = 0, Arg = 0, Rune =  []int}}, 
  450   Start = 1, NumCap = 2}
  451 </pre>
  452 
  453 
  454 <p>
  455 We can step into the <code>String</code>function call with <code>"s"</code>:
  456 </p>
  457 
  458 <pre>
  459 (gdb) <b>s</b>
  460 regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/user/go/src/regexp/regexp.go:97
  461 97      func (re *Regexp) String() string {
  462 </pre>
  463 
  464 <p>
  465 Get a stack trace to see where we are:
  466 </p>
  467 
  468 <pre>
  469 (gdb) <b>bt</b>
  470 #0  regexp.(*Regexp).String (re=0xf84068d070, noname=void)
  471     at /home/user/go/src/regexp/regexp.go:97
  472 #1  0x0000000000425615 in regexp.TestFind (t=0xf840688b60)
  473     at /home/user/go/src/regexp/find_test.go:151
  474 #2  0x0000000000430233 in testing.tRunner (t=0xf840688b60, test=0x5747b8)
  475     at /home/user/go/src/testing/testing.go:156
  476 #3  0x000000000040ea6f in runtime.initdone () at /home/user/go/src/runtime/proc.c:243
  477 ....
  478 </pre>
  479 
  480 <p>
  481 Look at the source code:
  482 </p>
  483 
  484 <pre>
  485 (gdb) <b>l</b>
  486 92              mu      sync.Mutex
  487 93              machine []*machine
  488 94      }
  489 95
  490 96      // String returns the source text used to compile the regular expression.
  491 97      func (re *Regexp) String() string {
  492 98              return re.expr
  493 99      }
  494 100
  495 101     // Compile parses a regular expression and returns, if successful,
  496 </pre>
  497 
  498 <h3 id="Pretty_Printing">Pretty Printing</h3>
  499 
  500 <p>
  501 GDB's pretty printing mechanism is triggered by regexp matches on type names.  An example for slices:
  502 </p>
  503 
  504 <pre>
  505 (gdb) <b>p utf</b>
  506 $22 =  []uint8 = {0 '\000', 0 '\000', 0 '\000', 0 '\000'}
  507 </pre>
  508 
  509 <p>
  510 Since slices, arrays and strings are not C pointers, GDB can't interpret the subscripting operation for you, but
  511 you can look inside the runtime representation to do that (tab completion helps here):
  512 </p>
  513 <pre>
  514 
  515 (gdb) <b>p slc</b>
  516 $11 =  []int = {0, 0}
  517 (gdb) <b>p slc-&gt;</b><i>&lt;TAB&gt;</i>
  518 array  slc    len    
  519 (gdb) <b>p slc->array</b>
  520 $12 = (int *) 0xf84057af00
  521 (gdb) <b>p slc->array[1]</b>
  522 $13 = 0</pre>
  523 
  524 
  525 
  526 <p>
  527 The extension functions $len and $cap work on strings, arrays and slices:
  528 </p>
  529 
  530 <pre>
  531 (gdb) <b>p $len(utf)</b>
  532 $23 = 4
  533 (gdb) <b>p $cap(utf)</b>
  534 $24 = 4
  535 </pre>
  536 
  537 <p>
  538 Channels and maps are 'reference' types, which gdb shows as pointers to C++-like types <code>hash&lt;int,string&gt;*</code>.  Dereferencing will trigger prettyprinting
  539 </p>
  540 
  541 <p>
  542 Interfaces are represented in the runtime as a pointer to a type descriptor and a pointer to a value.  The Go GDB runtime extension decodes this and automatically triggers pretty printing for the runtime type.  The extension function <code>$dtype</code> decodes the dynamic type for you (examples are taken from a breakpoint at <code>regexp.go</code> line 293.)
  543 </p>
  544 
  545 <pre>
  546 (gdb) <b>p i</b>
  547 $4 = {str = "cbb"}
  548 (gdb) <b>whatis i</b>
  549 type = regexp.input
  550 (gdb) <b>p $dtype(i)</b>
  551 $26 = (struct regexp.inputBytes *) 0xf8400b4930
  552 (gdb) <b>iface i</b>
  553 regexp.input: struct regexp.inputBytes *
  554 </pre>