diff options
author | Olly Betts <olly@survex.com> | 2022-03-07 14:19:34 +1300 |
---|---|---|
committer | Olly Betts <olly@survex.com> | 2022-03-07 14:24:48 +1300 |
commit | 46bdb1bb29500e645e9426c07889af4a6224354e (patch) | |
tree | 2f274a973ab494bc63cf1c9300a44d322cd4a9b9 | |
parent | 8dbcd710ff15aee3897043630f64f50c710c04f2 (diff) | |
download | swig-46bdb1bb29500e645e9426c07889af4a6224354e.tar.gz |
Add/update docs for Malloc(), Exit(), etc
See #2223
-rw-r--r-- | Doc/Devel/cmdopt.html | 4 | ||||
-rw-r--r-- | 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>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> |