src/newlib/winsup/doc/setup-maxmem.xml

<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>

<para>
Cygwin's heap is extensible.  However, it does start out at a fixed size
and attempts to extend it may run into memory which has been previously
allocated by Windows.  In some cases, this problem can be solved by
changing a field in the file header which is utilized by Cygwin since
to keep the initial size of the application heap.  If the field contains 0,
which is the default, the application heap defaults to a size of 384 Megabyte
on 32 bit Cygwin, 512 Megabyte on 64 bit Cygwin.  If the field is set to any
other value between 4 and 2048, Cygwin tries to reserve as much Megabytes
for the application heap.  The field used for this is the "LoaderFlags" field
in the NT-specific PE header structure
(<literal>(IMAGE_NT_HEADER)->OptionalHeader.LoaderFlags</literal>).</para>

<para>
This value can be changed for any executable by using a more recent version
of the <command>peflags</command> tool from the <literal>rebase</literal>
Cygwin package.  Example:

<screen>
$ peflags --cygwin-heap foo.exe
foo.exe: initial Cygwin heap size: 0 (0x0) MB
$ peflags --cygwin-heap=500 foo.exe
foo.exe: initial Cygwin heap size: 500 (0x1f4) MB
</screen>
</para>

<para>
Heap memory can be allocated up to the size of the biggest available free
block in the processes virtual memory (VM).  By default, the VM per process
is 2 GB for 32 processes.  To get more VM for a process, the executable
must have the "large address aware" flag set in the file header.  You can
use the aforementioned <command>peflags</command> tool to set this flag.
On 64 bit systems this results in a 4 GB VM for a process started from that
executable.  On 32 bit systems you also have to prepare the system to allow
up to 3 GB per process.  See the Microsoft article
<ulink url="http://msdn.microsoft.com/en-us/library/bb613473%28VS.85%29.aspx">4-Gigabyte Tuning</ulink>
for more information.
</para>

</sect1>