* faq-using.xml (faq.using.fixing-fork-failures): Add new FAQ.

	* overview2.sgml (ov-hi-process-problems): Describe some difficulties
	in implementing fork()

3 files changed, 94 insertions, 1 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 81b1fa6c6..ec133f757 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,9 @@
+2011-11-05  Jon TURNEY  <jon.turney@dronecode.org.uk>
+
+	* faq-using.xml (faq.using.fixing-fork-failures): Add new FAQ.
+	* overview2.sgml (ov-hi-process-problems): Describe some difficulties
+	in implementing fork()
+
 2011-10-28  Corinna Vinschen  <corinna@vinschen.de>
 
 	* new-features.sgml (ov-new1.7.10): Document getgrouplist.
diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml
index 7a09e2697..27f77837f 100644
--- a/winsup/doc/faq-using.xml
+++ b/winsup/doc/faq-using.xml
@@ -1099,7 +1099,7 @@ it.</para>
 IPv6 stack, see the <ulink url="http://www.microsoft.com/technet/network/ipv6/ipv6faq.mspx">Microsoft TechNet IPv6 FAQ article</ulink>
 </para></answer></qandaentry>
 
-<qandaentry id="faq.using.bloda">
+<qandaentry id="faq.using.bloda" xreflabel="BLODA">
 <question><para>What applications have been found to interfere with Cygwin?</para></question>
 <answer>
 
@@ -1199,3 +1199,39 @@ such as virtual memory paging and file caching.</para>
 </listitem>
 </itemizedlist></para>
 </answer></qandaentry>
+
+<qandaentry id='faq.using.fixing-fork-failures'>
+  <question><para>How do I fix <literal>fork()</literal> failures?</para></question>
+  <answer>
+  <para>Unfortunately, Windows does not use the fork/exec model of process creation
+  found in UNIX-like OSes, so it is difficult for Cygwin to implement a reliable and
+  correct <literal>fork()</literal>, which can lead to error messages such as:</para>
+  <para><itemizedlist>
+    <listitem>unable to remap <emphasis>somedll</emphasis> to same address as parent</listitem>
+    <listitem>couldn't allocate heap</listitem>
+    <listitem>died waiting for dll loading</listitem>
+    <listitem>child -1 - died waiting for longjmp before initialization</listitem>
+    <listitem>STATUS_ACCESS_VIOLATION</listitem>
+    <listitem>resource temporarily unavailable</listitem>
+  </itemizedlist></para>
+  <para>Potential solutions for the above errors:</para>
+  <para><itemizedlist>
+    <listitem>Restart whatever process is trying (and failing) to use
+    <literal>fork()</literal>. Sometimes Windows sets up a process
+    environment that is even more hostile to fork() than usual.</listitem>
+    <listitem>Ensure that you have eliminated (not just disabled) all
+    software on the <xref linkend="faq.using.bloda"/>.
+    </listitem>
+    <listitem>Read the 'rebase' package README in
+    <literal>/usr/share/doc/rebase/</literal>, and follow the
+    instructions there to run 'rebaseall'.</listitem>
+    </itemizedlist></para>
+  <para>Please note that installing new packages or updating existing
+  ones undoes the effects of rebaseall and often causes fork() failures
+  to reappear. If so, just run rebaseall again.
+  </para>
+  <para>See the <ulink url="http://cygwin.com/cygwin-ug-net/highlights.html#ov-hi-process">
+  process creation</ulink> section of the User's Guide for the technical reasons it is so
+  difficult to make <literal>fork()</literal> work reliably.</para>
+</answer>
+</qandaentry>
diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml
index 9e968f72f..5c1e8652f 100644
--- a/winsup/doc/overview2.sgml
+++ b/winsup/doc/overview2.sgml
@@ -346,6 +346,57 @@ cases, stubs of each of these Win32 processes may linger, waiting for
 their exec'd Cygwin process to exit.</para>
 </sect2>
 
+<sect3 id='ov-hi-process-problems'>
+<title>Problems with process creation</title>
+
+<para>The semantics of <literal>fork</literal> require that a forked
+child process have <emphasis>exactly</emphasis> the same address
+space layout as its parent. However, Windows provides no native
+support for cloning address space between processes and several
+features actively undermine a reliable <literal>fork</literal>
+implementation. Three issues are especially prevalent:</para>
+
+<para><itemizedlist>
+<listitem>DLL base address collisions. Unlike *nix shared
+libraries, which use "position-independent code", Windows shared
+libraries assume a fixed base address. Whenever the hard-wired
+address ranges of two DLLs collide (which occurs quite often), the
+Windows loader must "rebase" one of them to a different
+address. However, it may not resolve collisions consistently, and
+may rebase a different dll and/or move it to a different address
+every time. Cygwin can usually compensate for this effect when it
+involves libraries opened dynamically, but collisions among
+statically-linked dlls (dependencies known at compile time) are
+resolved before <literal>cygwin1.dll</literal> initializes and
+cannot be fixed afterward. This problem can only be solved by
+removing the base address conflicts which cause the problem,
+usually using the <literal>rebaseall</literal> tool.</listitem>
+
+<listitem>Address space layout randomization (ASLR). Starting with
+Vista, Windows implements ASLR, which means that thread stacks,
+heap, memory-mapped files, and statically-linked dlls are placed
+at different (random) locations in each process. This behaviour
+interferes with a proper <literal>fork</literal>, and if an
+unmovable object (process heap or system dll) ends up at the wrong
+location, Cygwin can do nothing to compensate (though it will
+retry a few times automatically).</listitem>
+
+<listitem>DLL injection by
+<ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda">
+BLODA</ulink>. Badly-behaved applications which
+inject dlls into other processes often manage to clobber important
+sections of the child's address space, leading to base address
+collisions which rebasing cannot fix. The only way to resolve this
+problem is to remove (usually uninstall) the offending
+app.</listitem></itemizedlist></para>
+
+<para>In summary, current Windows implementations make it
+impossible to implement a perfectly reliable fork, and occasional
+fork failures are inevitable.
+</para>
+
+</sect3>
+
 <sect2 id="ov-hi-signals"><title>Signals</title>
 <para>When
 a Cygwin process starts, the library starts a secondary thread for