From e6ea3b07e25b09481b010558f8bfdfb57dcbb85e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= <egil@erlang.org>
Date: Mon, 15 Oct 2012 16:22:47 +0200
Subject: doc: Document ERL_CRASH_DUMP_SECONDS behaviour

* heart reboot behaviour
* erl_crash.dump file write behaviour
---
 erts/doc/src/erl.xml         | 31 +++++++++++++++++++++++++++++++
 lib/kernel/doc/src/heart.xml | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 2dea477d99..f931445a3e 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -1040,6 +1040,37 @@
           the emulator will be allowed to spend writing a crash dump. When
           the given number of seconds have elapsed, the emulator will be
           terminated by a SIGALRM signal.</p>
+
+	  <p> If the environment variable is <em>not</em> set or it is set to zero seconds, <c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c>,
+		  the runtime system will not even attempt to write the crash dump file. It will just terminate.
+	  </p>
+	  <p> If the environment variable is set to negative valie, e.g. <c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c>,
+		  the runtime system will wait indefinitely for the crash dump file to be written.
+	  </p>
+	  <p> This environment variable is used in conjuction with
+		  <seealso marker="kernel:heart"><c>heart</c></seealso> if <c>heart</c> is running:
+	  </p>
+	  <taglist>
+		  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
+		  <item><p>
+				  Suppresses the writing a crash dump file entirely,
+				  thus rebooting the runtime system immediately.
+				  This is the same as not setting the environment variable.
+			  </p>
+		  </item>
+		  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
+		  <item><p>Setting the environment variable to a negative value will cause the
+				  termination of the runtime system to wait until the crash dump file
+				  has been completly written.
+			  </p>
+		  </item>
+		  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
+		  <item><p>
+				  Will wait for <c>S</c> seconds to complete the crash dump file and
+				  then terminate the runtime system.
+			  </p>
+		  </item>
+	  </taglist>
       </item>
       <tag><c><![CDATA[ERL_AFLAGS]]></c></tag>
       <item>
diff --git a/lib/kernel/doc/src/heart.xml b/lib/kernel/doc/src/heart.xml
index 26d1e27822..2826d3d00a 100644
--- a/lib/kernel/doc/src/heart.xml
+++ b/lib/kernel/doc/src/heart.xml
@@ -71,6 +71,39 @@
       timeout and try to reboot the system. This can happen, for
       example, if the system clock is adjusted automatically by use of
       NTP (Network Time Protocol).</p>
+
+  <p> If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> will <em>not</em> be written
+	  unless the environment variable <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set.
+  </p>
+
+    <pre>
+% <input>erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...</input></pre>
+  <p>
+	  Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the following behaviour on
+	  <c>heart</c>:
+  </p>
+  <taglist>
+	  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
+	  <item><p>
+			  Suppresses the writing a crash dump file entirely,
+			  thus rebooting the runtime system immediately.
+			  This is the same as not setting the environment variable.
+		  </p>
+	  </item>
+	  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
+	  <item><p> Setting the environment variable to a negative value will not reboot
+			  the runtime system until the crash dump file has been completly written.
+		  </p>
+	  </item>
+	  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
+	  <item><p>
+			  Heart will wait for <c>S</c> seconds to let the crash dump file be written.
+			  After <c>S</c> seconds <c>heart</c> will reboot the runtime system regardless of
+			  the crash dump file has been written or not.
+		  </p>
+	  </item>
+  </taglist>
+
     <p>In the following descriptions, all function fails with reason
       <c>badarg</c> if <c>heart</c> is not started.</p>
   </description>
-- 
cgit v1.2.3