Changes between Version 2 and Version 3 of rfc19_safememalloc

Timestamp:

Dec 30, 2007, 2:22:43 AM (16 years ago)

Author:

Even Rouault

Comment:

Add CPLSafeMalloc2 and CPLSafeMalloc3 API

rfc19_safememalloc

@@ -17 +17 @@
 
 {{{
-/* The following 2 functions check that the result of the multiplication */
-/* does not overflow the limits of size_t. 0 is returned in case of overflow */
-/* *pbOverflowFlag is set to TRUE if overflow has occured */
-size_t CPL_DLL VSISafeMul2( size_t mul1, size_t mul2, int *pbOverflowFlag);
-size_t CPL_DLL VSISafeMul3( size_t mul1, size_t mul2, size_t mul3, int *pbOverflowFlag);
+/**
+ This function returns (mul1 * mul2) and checks that the result of
+ the multiplication does not overflow the limits of size_t.
+ In case of overflow, 0 is returned, *pbOverflowFlag is set to TRUE
+ and a CE_Failure error is raised with CPLError()
+*/
+size_t CPL_DLL CPLSafeMul2( size_t mul1, size_t mul2, int *pbOverflowFlag);
 
-/* This function return the @size argument if it fits into an integer, or 0 in */
-/* case of overflow. */
-/* *pbOverflowFlag is set to TRUE if overflow has occured */
-int    CPL_DLL VSISafeSizetCastToInt( size_t size, int *pbOverflowFlag );
+/**
+ This function returns (mul1 * mul2 * mul3) and checks that the result of
+ the multiplication does not overflow the limits of size_t.
+ In case of overflow, 0 is returned, *pbOverflowFlag is set to TRUE
+ and a CE_Failure error is raised with CPLError()
+*/
+size_t CPL_DLL CPLSafeMul3( size_t mul1, size_t mul2, size_t mul3, int *pbOverflowFlag);
+
+/**
+ This function return the @size argument if it fits into an integer.
+ In case of overflow, 0 is returned, *pbOverflowFlag is set to TRUE
+ and a CE_Failure error is raised with CPLError()
+*/
+int    CPL_DLL CPLSafeSizetCastToInt( size_t size, int *pbOverflowFlag );
 }}}
 
 Note: the pbOverflowFlag parameter is new in comparison to the initial proposition of ticket #2075 .
 
-Implementation of CPLMalloc, CPLCalloc, CPLRealloc, VSIMalloc, VSICalloc, VSIRealloc will not be changed. Developers are encouraged to use the VSI functions rather than the CPL ones since CPLMalloc will abort the process when doing a too large allocation, whereas VSIMalloc will return a NULL pointer.
+
+To avoid verbosity when using the CPLSafeMulX calls for memory allocation, the following helper functions will also be provided.
+
+{{{
+/**
+ CPLSafeMalloc2 allocates (nSize1 * nSize2) bytes.
+ In case of overflow of the multiplication, or if memory allocation fails, a
+ NULL pointer is returned and a CE_Failure error is raised with CPLError().
+ If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned.
+ CPLFree() or VSIFree() can be used to free memory allocated by this function.
+*/
+void CPL_DLL *CPLSafeMalloc2( size_t nSize1, size_t nSize2 );
+
+/**
+ CPLSafeMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.
+ In case of overflow of the multiplication, or if memory allocation fails, a
+ NULL pointer is returned and a CE_Failure error is raised with CPLError().
+ If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be returned.
+ CPLFree() or VSIFree() can be used to free memory allocated by this function.
+*/
+void CPL_DLL *CPLSafeMalloc3( size_t nSize1, size_t nSize2, size_t nSize3 );
+}}}
+
+Implementation of CPLMalloc, CPLCalloc, CPLRealloc, VSIMalloc, VSICalloc, VSIRealloc will not be changed. Developers are encouraged to use the CPLSafeMallocX functions instead of doing CPLMalloc(x * y) or VSIMalloc(x * y).
 
 == Implementation steps ==