+ <para>
+ Tip: setting something like <literal>GHCRTS=-M2G</literal>
+ in your environment is a handy way to avoid Haskell programs
+ growing beyond the real memory in your machine, which is
+ easy to do by accident and can cause the machine to slow to
+ a crawl until the OS decides to kill the process (and you
+ hope it kills the right one).
+ </para>
+ </sect3>
+
+ <sect3 id="rts-hooks">
+ <title>“Hooks” to change RTS behaviour</title>
+
+ <indexterm><primary>hooks</primary><secondary>RTS</secondary></indexterm>
+ <indexterm><primary>RTS hooks</primary></indexterm>
+ <indexterm><primary>RTS behaviour, changing</primary></indexterm>
+
+ <para>GHC lets you exercise rudimentary control over the RTS
+ settings for any given program, by compiling in a
+ “hook” that is called by the run-time system. The RTS
+ contains stub definitions for all these hooks, but by writing your
+ own version and linking it on the GHC command line, you can
+ override the defaults.</para>
+
+ <para>Owing to the vagaries of DLL linking, these hooks don't work
+ under Windows when the program is built dynamically.</para>
+
+ <para>The hook <literal>ghc_rts_opts</literal><indexterm><primary><literal>ghc_rts_opts</literal></primary>
+ </indexterm>lets you set RTS
+ options permanently for a given program, in the same way as the
+ newer <option>-with-rtsopts</option> linker option does. A common use for this is
+ to give your program a default heap and/or stack size that is
+ greater than the default. For example, to set <literal>-H128m
+ -K1m</literal>, place the following definition in a C source
+ file:</para>
+
+<programlisting>
+char *ghc_rts_opts = "-H128m -K1m";
+</programlisting>
+
+ <para>Compile the C file, and include the object file on the
+ command line when you link your Haskell program.</para>
+
+ <para>These flags are interpreted first, before any RTS flags from
+ the <literal>GHCRTS</literal> environment variable and any flags
+ on the command line.</para>
+
+ <para>You can also change the messages printed when the runtime
+ system “blows up,” e.g., on stack overflow. The hooks
+ for these are as follows:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>
+ <function>void OutOfHeapHook (unsigned long, unsigned long)</function>
+ <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm>
+ </term>
+ <listitem>
+ <para>The heap-overflow message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>void StackOverflowHook (long int)</function>
+ <indexterm><primary><function>StackOverflowHook</function></primary></indexterm>
+ </term>
+ <listitem>
+ <para>The stack-overflow message.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>void MallocFailHook (long int)</function>
+ <indexterm><primary><function>MallocFailHook</function></primary></indexterm>
+ </term>
+ <listitem>
+ <para>The message printed if <function>malloc</function>
+ fails.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>For examples of the use of these hooks, see GHC's own
+ versions in the file
+ <filename>ghc/compiler/parser/hschooks.c</filename> in a GHC
+ source tree.</para>
+ </sect3>
+
+ </sect2>