From 46bdb1bb29500e645e9426c07889af4a6224354e Mon Sep 17 00:00:00 2001
From: Olly Betts <olly@survex.com>
Date: Mon, 7 Mar 2022 14:19:34 +1300
Subject: [PATCH] Add/update docs for Malloc(), Exit(), etc

See #2223
---
 Doc/Devel/cmdopt.html    |  4 ++--
 Doc/Devel/internals.html | 28 ++++++++++++++++++++++++----
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/Doc/Devel/cmdopt.html b/Doc/Devel/cmdopt.html
index 5e90d2aba..10dc73170 100644
--- a/Doc/Devel/cmdopt.html
+++ b/Doc/Devel/cmdopt.html
@@ -60,7 +60,7 @@ and issues an error message if any unconsumed arguments are found.
 <b><tt>void Swig_check_options()</tt></b>
 <blockquote>
 Checks all command line options to see if they have all been processed.  If not, an error message is generated and
-execution terminates with a call to <tt>exit()</tt>.   This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
+SWIG exits.   This function is currently invoked in <tt>Source/Modules/main.cxx</tt> just before SWIG starts any processing of input files.
 </blockquote>
 
 <h2>Utility Function</h2>
@@ -68,7 +68,7 @@ execution terminates with a call to <tt>exit()</tt>.   This function is currentl
 <b><tt>void Swig_arg_error())</tt></b>
 
 <blockquote>
-A generic function that issues an error message about being unable to parse command line options.  SWIG is terminated by a call to <tt>exit()</tt>.
+A generic function that issues an error message about being unable to parse command line options and SWIG exits.
 
 </body>
 </html>
diff --git a/Doc/Devel/internals.html b/Doc/Devel/internals.html
index 0fc6623e8..d003d9dea 100644
--- a/Doc/Devel/internals.html
+++ b/Doc/Devel/internals.html
@@ -519,7 +519,27 @@ hash item: hashval3 [h3]
 <h3>2.10 Utility functions </h3>
 </a>
 
-[ TODO ]
+<p>
+DOH wraps some standard C library functions - these wrapped versions should
+always be used in code in the SWIG tool itself (but not in generated code).
+When compiling with GCC or clang, the original library function names are
+marked as "poisoned" symbols so you should get an error if you accidentally
+use one of the unwrapped functions.  These functions are:
+
+<ul>
+    <li><tt>Calloc(m,n)</tt> : wrapper for <tt>calloc(m,n)</tt> which exits on memory failure so never returns <tt>NULL</tt>.
+    <li><tt>Malloc(n)</tt> : wrapper for <tt>malloc(n)</tt> which exits on memory failure so never returns <tt>NULL</tt>.
+    <li><tt>Realloc(p,n)</tt> : wrapper for <tt>realloc(p,n)</tt> which exits on memory failure so never returns <tt>NULL</tt>.
+    <li><tt>Free(p)</tt> : wrapper for <tt>free(p)</tt> (doesn't currently do anything special, really done for consistency with <tt>Malloc()</tt> etc).
+    <li><tt>Exit(r)</tt> : wrapper for <tt>exit(r)</tt> which for SWIG removes generated files if <tt>r&gt;0</tt>.
+</ul>
+
+<tt>abort()</tt> is also poisoned - please use <tt>Exit(EXIT_FAILURE)</tt> instead so that generated files are removed.
+</p>
+
+<p>
+[ TODO document others ]
+</p>
 
 <a name="3" href="#i3">
 <h2>3. Types and Typemaps</h2>
@@ -1194,12 +1214,12 @@ that are used after they have been deleted. This is because the DOH memory alloc
 grabs a chunk of memory from the C memory allocator and manages the usage internally.
 Stale DOH object usage can be checked for by defining <tt>DOH_DEBUG_MEMORY_POOLS</tt> in 
 <tt>memory.c</tt>. If an attempt to use an object is made after the reference count is
-zero, an assertion is triggered instead of quietly re-using the stale object...
+zero, a fatal error is triggered instead of quietly re-using the stale object:
 </p>
 
 <blockquote>
 <pre>
-swig: DOH/memory.c:91: DohCheck: Assertion `!DOH_object_already_deleted' failed.
+Fatal internal error: Attempt to delete a non-DOH object.
 </pre>
 </blockquote>
 
@@ -1209,7 +1229,7 @@ only recommended for diagnosing memory corruption problems.
 </p>
 
 <hr>
-Copyright (C) 1999-2010 SWIG Development Team.
+Copyright (C) 1999-2022 SWIG Development Team.
 
 </body>
 </html>