_debug_tfree -- Release Tiled Memory (OS/2)

Format

#include <stdlib.h>    /* also in <malloc.h> */
void _debug_tfree(void *ptr, const char *file,
                  size_t line);

Language Level: Extension
_debug_tfree is the debug version of _tfree. Like _tfree, it frees the block of tiled memory pointed to by ptr. _debug_tfree also sets each block of freed memory to 0xFB, so you can easily locate instances where your program uses the data in freed memory.

In addition, _debug_tfree makes an implicit call to the _theap_check, and stores the file name file and the line number line where the memory is freed. This information can be used later by the _theap_check and _tdump_allocated or _tdump_allocated_delta functions.

To use _debug_tfree, you must compile with the debug memory (/Tm) and tiled memory (/Gt) compiler options. These options map all free calls to _debug_tfree.

Note: The /Tm /Gt options map all calls to regular memory management functions to their tiled debug versions. To prevent a call from being mapped, parenthesize the function name.

_debug_tfree works just like _debug_free except that it frees tiled memory instead of regular memory. If you have objects that may be accessed by 16-bit code, you should store them in tiled memory. Tiled memory is guaranteed not to cross 64K boundaries, as long as the object is less than 64K in size. Objects larger than 64K in size are aligned on 64K boundaries, but will also cross 64K boundaries. You can also create your own heaps of tiled memory.

Return Value
There is no return value.

Example
This example allocates a 100-byte block of memory. It then frees the block twice. The second _debug_tfree call invokes _theap_check, which detects the error, generates several messages, and stops the program.

Note: You must compile this example with the /Tm /Gt options to map the free calls to _debug_tfree.

#include <stdlib.h>
#include <stdio.h>
int main(void)
{
   char *ptr;
   if (NULL == (ptr = (char*)malloc(100))) {
      puts("Could not allocate memory block.\n");
      exit(EXIT_FAILURE);
   }
   free(ptr);   /* free the object */
   free(ptr);   /* free the object again should cause an error */
   return 0;
   /**********************************************************************
      The output should be similar to :
      Object 0x00080120 provided is either invalid or was overwritten at
      0x0008011c.
      Memory error detected at line 13 of _debug_tfree.c.
   **********************************************************************/
}


Managing Memory with Multiple Heaps
Memory Management


_debug_free -- Release Memory
_debug_tcalloc -- Reserve and Initialize Tiled Memory
_debug_tmalloc -- Reserve Tiled Memory
_debug_trealloc -- Reallocate Tiled Memory Block
free -- Release Storage Blocks
_tdump_allocated -- Get Information about Allocated Tiled Memory
_tdump_allocated_delta -- Get Information about Allocated Tiled Memory
tfree -- Free Tield Storage Block
_theap_check -- Validate User Memory Heap
<malloc.h>
<stdlib.h>
/Tm compiler option
/Gt compiler option