docs/cygwin_dll_remapping_failure.md

   1 # Handling repeated failures of rebaseall to allow cygwin remaps
   2
   3 Sometimes DLLs over which cygwin has no control get mapped into cygwin
   4 processes at locations that cygwin has chosen for its libraries.
   5 This has been seen primarily with anti-virus DLLs. When this occurs,
   6 cygwin must be instructed during the rebase to avoid the area of
   7 memory where that DLL is mapped.
   8
   9 ## Background
  10
  11 Some background for this is available on
  12 http://www.dont-panic.cc/capi/2007/10/29/git-svn-fails-with-fatal-error-unable-to-remap/
  13
  14 Because of unix fork semantics (presumably), cygwin libraries must be
  15 mapped in the same location in both parent and child of a fork.  All
  16 cygwin libraries have hints in them as to where they should be mapped
  17 in a processes address space; if those hints are followed, each
  18 library will be mapped in the same location in both address spaces.
  19 However, Windows is perfectly happy mapping a DLL anywhere in the
  20 address space; the hint is not considered controlling.  The remapping
  21 error occurs when a cygwin process starts and one of its libraries
  22 cannot be mapped to the location specified by its hint.
  23
  24 /usr/bin/rebaseall changes the DLL hints for all of the cygwin
  25 libraries so that there are no inter-library conflicts; it does this
  26 by choosing a contiguous but not overlapping library layout starting
  27 at a base address and working down.  This process makes sure there are
  28 no intra-cygwin conflicts, but cannot deal with conflicts with
  29 external DLLs that are in cygwin process address spaces
  30 (e.g. anti-virus DLLs).
  31
  32 To handle this case, you need to figure out what the problematic
  33 non-cygwin library is, where it is in the address space, and do the
  34 rebase all so that no cygwin hints map libraries to that location.
  35
  36 ## Details
  37
  38 *   Download the ListDLLs executable from
  39     [sysinternals](http://technet.microsoft.com/en-us/sysinternals/bb896656.aspx)
  40 *   Run it as administrator while some cygwin commands are running.
  41 *   Scan the output for the cygwin process (identifiable by the command) and for
  42     DLLs in that process that do not look like cygwin DLLs (like an AV). Note
  43     the location of those libraries (there will usually only be the one).
  44 *   Pick an address space location lower than its starting address.
  45 *   Quit all cygwin processes.
  46 *   Run a windows command shell as administrator
  47 *   cd in \cygwin\bin
  48 *   Run `ash /usr/bin/rebaseall -b <base address>` (This command can also take a
  49     `-v` flag if you want to see the DLL layout.)
  50
  51 That should fix the problem.
  52
  53 ## Failed rebaseall
  54
  55 If you pick a base address that is too low, you may end up with a broken cygwin
  56 install. You can reinstall it by running cygwin's setup.exe again, and on the
  57 package selection page, clicking the "All" entry to Reinstall. You may have to
  58 do this twice, as you may get errors on the first reinstall pass.