From 325268e1c1426c2178d7ee25594a1b8a0d771a2b Mon Sep 17 00:00:00 2001
From: Christopher Faylor <me@cgf.cx>
Date: Wed, 12 Jun 2002 16:06:10 +0000
Subject: [PATCH] Add dumper.exe words from Egor Duda.

---
 winsup/utils/utils.sgml | 46 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml
index 9273dfea0..e371619a7 100644
--- a/winsup/utils/utils.sgml
+++ b/winsup/utils/utils.sgml
@@ -765,5 +765,51 @@ print the message but does return the non-zero exit code.</para>
 
 </sect2>
 
+<sect2 id="dumper"><title>dumper</title>
+
+<screen>
+Usage: dumper [OPTION] FILENAME WIN32PID
+Dump core from WIN32PID to FILENAME.core
+ -d, --verbose  be verbose while dumping
+ -h, --help     output help information and exit
+ -q, --quiet    be quiet while dumping (default)
+ -v, --version  output version information and exit
+</screen>
+
+<para>The <command>dumper</command> utility can be used to create
+core dump of running windows process. This core dump can be later loaded
+to gdb an analyzed. One common way to use <command>dumper</command> is to
+plug it into cygwin's Just-In-Time debugging facility by adding
+
+<screen>
+error_start=x:\path\to\dumper.exe
+</screen>
+
+to <em>CYGWIN</em> environment variable. Please note that
+<literal>x:\path\to\dumper.exe</literal> is win32-style and not cygwin
+path. If <literal>error_start</literal> is set this way, then dumper will
+be started whenever some program encounters fatal error.
+</para>
+
+<para>
+<command>dumper</command> can be also be started from command line to create
+core dump of any running process. Unfortunately, because of windows API
+limitation, when core dump is created and <command>dumper</command> exits,
+the target process is terminated too.
+</para>
+
+<para>
+To save the space in core dump, <command>dumper</command> doesn't write those
+portions of target process' memory space that are loaded from executable and
+dll files and are unchangeable, such as program code and debug info. Instead,
+<command>dumper</command> saves paths to files which contain that data. When
+core dump is loaded into gdb, it uses these paths to load appropriate files.
+That means that if you create core dump on one machine and try to debug it on
+other, you'll need to place identical copies of executable and dlls in the same
+directories as on machine where core dump has been created.
+</para>
+
+</sect2>
+
 </sect1>