- </sect2>
-
- <sect2>
- <title>Linker flags to change RTS behaviour</title>
-
- <indexterm><primary>RTS behaviour, changing</primary></indexterm>
-
- <para>
- GHC lets you exercise rudimentary control over the RTS settings
- for any given program, by using the <literal>-with-rtsopts</literal>
- linker flag. For example, to set <literal>-H128m -K1m</literal>,
- link with <literal>-with-rtsopts="-H128m -K1m"</literal>.
- </para>
-
- </sect2>
-
- <sect2 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>
- </sect2>