winsup/cygwin/DevDocs/how-to-debug-cygwin.txt

   1 Contributed by Egor Duda
   2
   3 So, your favorite program has crashed?  And did you say something about
   4 'stackdump'?  Or it just prints its output from left to right and
   5 upside-down?  Well, you can file an angry bug report and wait until some
   6 of the core developers try to reproduce your problem, try to find what's
   7 the matter with your program and cygwin and fix the bug, if any.  But
   8 you can do something better than that.  You can debug the problem
   9 yourself, and even if you can't fix it, your analysis may be very
  10 helpful.  Here's the (incomplete) howto on cygwin debugging.
  11
  12 1.  First things first
  13
  14     The first thing you'll need to do is to build cygwin1.dll and your
  15     crashed application from sources.  To debug them you'll need debug
  16     information, which is normally stripped from executables.  You probably
  17     also want to build a version of the dll with more debugging capabilities
  18     by reconfiguring your build directory, specifying the --enable-debugging
  19     option to configure.
  20
  21 2. Creating a known-working cygwin debugging environment
  22
  23    - create a separate directory, say, c:\cygdeb, and put known-working
  24      cygwin1.dll and gdb.exe in it.
  25    - create a wrapper c:\cygdeb\debug_wrapper.cmd:
  26
  27 ========= debug_wrapper.cmd =========
  28 rem setting CYGWIN_TESTING environment variable makes cygwin application
  29 rem not to interfere with other already running cygwin applications.
  30 set CYGWIN_TESTING=1
  31 c:\cygdeb\gdb.exe -nw %1 %2
  32 ===================================
  33
  34 3. Using cygwin's JIT debugging facility
  35
  36    add 'error_start=c:\cygdeb\debug_wrapper.cmd' to CYGWIN environment
  37    variable. When some application encounters critical error, cygwin will stop
  38    it and execute debug_wrapper.cmd, which will run gdb and make it to attach to
  39    the crashed application.
  40
  41 4. Strace
  42
  43    You can run your program under 'strace' utility, described if user's manual.
  44    If you know where the problem approximately is, you can add a bunch of
  45    additional debug_printf()s in the source code and see what they print in
  46    strace log. There's one common problem with this method, that some bugs
  47    may mysteriously disappear once the program is run under strace. Then the
  48    bug is likely a race condition. strace has two useful options to deal with
  49    such situation: -b enables buffering of output and reduces additional
  50    timeouts introduced by strace, and -m option allows you to mask certain
  51    classes of *_printf() functions, reducing timeouts even more.
  52
  53    Note that strace does not use the cygwin DLL and so any process that it
  54    starts does not inherit a cygwin environment.  It is equivalent to starting
  55    a program from the command prompt.
  56
  57 5. Problems at early startup
  58
  59    Sometimes, something crashes at the very early stages of application
  60    initialization, when JIT debugging facility is not yet active. Ok, there's
  61    another environment variable that may help. Create program_wrapper.cmd:
  62
  63 ========= program_wrapper.cmd =========
  64 rem setting CYGWIN_SLEEP environment variable makes cygwin application
  65 rem to sleep for x milliseconds at startup
  66 set CYGWIN_SLEEP=20000
  67 c:\some\path\bad_program.exe some parameters
  68 ===================================
  69
  70    Now, run program_wrapper.cmd. It should print running program pid.
  71    After starting program_wrapper.cmd you've got 20 seconds to open another
  72    window, cd to c:\cygdeb in it, run gdb there and in gdb prompt type
  73
  74    (gdb) attach <pid>
  75
  76    where <pid> is the pid that program_wrapper.cmd have printed.
  77    After that you can normally step through the code in cygwin1.dll and
  78    bad_program.exe
  79
  80 6. More problems at early startup
  81
  82    You can also set a CYGWIN_DEBUG variable to force the debugger to pop up
  83    only when a certain program is run:
  84
  85 set CYGWIN_DEBUG=cat.exe:gdb.exe
  86
  87    This will force gdb.exe to start when the program name contains the string
  88    "cat.exe".  The ':gdb.exe' isn't really needed, since it is the default.
  89    It is just there to show how you can specify a program to run when the
  90    program starts.  You can optionally set a breakpoint on "break_here"
  91    once the debugger pops up and then you can single step through the
  92    initialization process.
  93
  94    Note that it bears repeating that both of the above options are *only*
  95    available when configuring cygwin with --enable-debugging.
  96
  97 7. Heap corruption
  98
  99    If your program crashes at malloc() or free() or when it references some
 100    malloc()'ed memory, it looks like heap corruption. You can configure and
 101    build special version of cygwin1.dll which includes heap sanity checking.
 102    To do it, just add --enable-malloc-debugging option to configure. Be warned,
 103    however, that this version of dll is _very_ slow (10-100 times slower than
 104    normal), so use it only when absolutely necessary.
 105
 106 8. Program dies when running under strace
 107
 108    If your program crashes when you run it using strace but runs ok (or has a
 109    different problem) otherwise, then there may be a problem in one of the
 110    strace *_printf statements.  Usually this is caused by a change in arguments
 111    resulting in a %s being used with something other than a pointer to a
 112    string.
 113
 114    To debug this scenario, do something like this:
 115
 116     bash$ gdb -nw yourapp.exe
 117     (gdb) dll cygwin1
 118     (gdb) l dll_crt0_1
 119     (gdb) b <<first line in the function>>
 120     (gdb) run
 121     (gdb) set strace._active=1
 122     (gdb) continue
 123
 124    The program will then run in "strace mode", calling each strace *_printf,
 125    just like it does when run under the strace program.  Eventually, the
 126    program will crash, probably in small_printf.  At that point, a 'bt'
 127    command should show you the offending call to strace_printf with the
 128    improper format string.