Watcom C Library : _heapchk Functions, _heapenable, _heapgrow Functions, _heapmin Functions, _heapset Functions
Watcom C Reference/G - H - I 2021. 6. 30. 17:44
Watcom C Library Reference : _heapchk Functions, _heapenable, _heapgrow Functions, _heapmin Functions, _heapset Functions
_heapchk Functions
Synopsis : #include <malloc.h>
int _heapchk ( void );
int _bheapchk( __segment seg );
int _fheapchk( void );
int _nheapchk( void );
Description : The _heapchk functions along with heapset and heapwalk are provided for debugging heap related problems in programs.
The _heapchk functions perform a consistency check on the unallocated memory space or "heap". The consistency check determines whether all the heap entries are valid. Each function checks a particular heap, as listed below:
| Function | Heap Checked |
| _heapchk | Depends on data model of the program |
| _bheapchk | Based heap specified by seg value; _NULLSEG specifies all based heaps |
| _fheapchk | Far heap (outside the default data segment) |
| _nheapchk | Near heap (inside the default data segment) |
In a small data memory model, the _heapchk function is equivalent to the _nheapchk function; in a large data memory model, the _heapchk function is equivalent to the _fheapchk function.
Returns : All four functions return one of the following manifest constants which are defined in <malloc.h>.
| Constant | Meaning |
| _HEAPOK | The heap appears to be consistent. |
| _HEAPEMPTY | The heap is empty. |
| _HEAPBADBEGIN | The heap has been damaged. |
| _HEAPBADNODE | The heap contains a bad node, or is damaged. |
See Also : _heapenable, _heapgrow, _heapmin, _heapset, _heapshrink, _heapwalk
Example :
#include <stdio.h>
#include <malloc.h>
void main( )
{
char *buffer;
buffer = (char *)malloc( 80 );
malloc( 1024 );
free ( buffer );
switch( _heapchk( ) ) {
case _HEAPOK :
printf( "OK - heap is good\n" );
break;
case _HEAPEMPTY :
printf( "OK - heap is empty\n" );
break;
case _HEAPBADBEGIN :
printf( "ERROR - heap is damaged\n" );
break;
case _HEAPBADNODE :
printf( "ERROR - bad node in heap\n" );
break;
}
}
Classification : WATCOM
Systems : _heapchk - All
_fheapchk - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_nheapchk - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT
_bheapchk - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_heapenable
Synopsis : #include <malloc.h>
int heapenable( int enabled );
Description : The _heapenable function is used to control attempts by the heap allocation manager to request more memory from the operating system's memory pool. If enabled is 0 then all further allocations which would normally go to the operating system for more memory will instead fail and return NULL. If enabled is 1 then requests for more memory from the operating system's memory pool are re-enabled.
This function can be used to impose a limit on the amount of system memory that is allocated by an application. For example, if an application wishes to allocate no more than 200K bytes of memory, it could allocate 200K and immediately free it. It can then call _heapenable to disable any further requests from the system memory pool. After this, the application can allocate memory from the 200K pool that it has already obtained.
Returns : The return value is the previous state of the system allocation flag.
See Also : _heapchk, _heapgrow, _heapmin, _heapset, _heapshrink, _heapwalk
Example :
#include <stdio.h>
#include <malloc.h>
void main( )
{
char *p;
p = malloc( 200 * 1024 );
if( p != NULL ) free( p );
_heapenable( 0 );
/* allocate memory from a pool that has been capped at 200K */
}
Classification : WATCOM
Systems : All
_heapgrow Functions
Synopsis : #include <malloc.h>
void _heapgrow( void );
void _nheapgrow( void );
void _fheapgrow( void );
Description : The _nheapgrow function attempts to grow the near heap to the maximum size of 64K. You will want to do this in the small data models if you are using both malloc and _fmalloc or halloc. Once a call to _fmalloc or halloc has been made, you may not be able to allocate any memory with malloc unless space has been reserved for the near heap using either malloc, sbrk or _nheapgrow.
The _fheapgrow function doesn't do anything to the heap because the far heap will be extended automatically when needed. If the current far heap cannot be extended, then another far heap will be started.
In a small data memory model, the _heapgrow function is equivalent to the _nheapgrow function; in a large data memory model, the _heapgrow function is equivalent to the _fheapgrow function.
Returns : These functions do not return a value.
See Also : _heapchk, _heapenable, _heapmin, _heapset, _heapshrink, _heapwalk
Example :
#include <stdio.h>
#include <malloc.h>
void main( )
{
char *p, *fmt_string;
fmt_string = "Amount of memory available is %u\n";
printf( fmt_string, _memavl( ) );
_nheapgrow( );
printf( fmt_string, memavl( ) );
p = (char *) malloc( 2000 );
printf( fmt_string, memavl( ) );
}
produces the following :
Amount of memory available is 0
Amount of memory available is 62732
Amount of memory available is 60730
Classification : WATCOM
Systems : _heapgrow - All
_fheapgrow - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_nheapgrow - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT
_heapmin Functions
Synopsis : #include <malloc.h>
int _heapmin( void );
int _bheapmin( __segment seg );
int _fheapmin( void );
int _nheapmin( void );
Description : The _heapmin functions attempt to shrink the specified heap to its smallest possible size by returning all free entries at the end of the heap back to the system. This can be used to free up as much memory as possible before using the system function or one of the spawn functions.
The various _heapmin functions shrink the following heaps:
| Function | Heap Minimized |
| _heapmin | Depends on data model of the program |
| _bheapmin | Based heap specified by seg value; _NULLSEG specifies all based heaps |
| _fheapmin | Far heap (outside the default data segment) |
| _nheapmin | Near heap (inside the default data segment) |
In a small data memory model, the _heapmin function is equivalent to the _nheapmin function; in a large data memory model, the _heapmin function is equivalent to the _fheapmin function. It is identical to the _heapshrink function.
Returns : These functions return zero if successful, and non-zero if some error occurred.
See Also : _heapchk, _heapenable, _heapgrow, _heapset, _heapshrink, _heapwalk
Example :
#include <stdlib.h>
#include <malloc.h>
void main( )
{
_heapmin( );
system( "chdir c:\\watcomc" );
}
Note the use of two adjacent backslash characters(\) within character-string constants to signify a single backslash.
Classification : WATCOM
Systems : _heapmin - All
_bheapmin - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_fheapmin - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_nheapmin - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT
_heapset Functions
Synopsis : #include <malloc.h>
int _heapset( unsigned char fill_char );
int _bheapset( __segment seg, unsigned char fill_char);
int _fheapset( unsigned char fill_char );
int _nheapset( unsigned char fill_char );
Description : The _heapset functions along with _heapchk and _heapwalk are provided for debugging heap related problems in programs.
The _heapset functions perform a consistency check on the unallocated memory space or "heap" just as _heapchk does, and sets the heap's free entries with the fill_char value.
Each function checks and sets a particular heap, as listed below:
| Function | Heap Filled |
| _heapset | Depends on data model of the program |
| _bheapset | Based heap specified by seg value; _NULLSEG specifies all based heaps |
| _fheapset | Far heap (outside the default data segment) |
| _nheapset | Near heap (inside the default data segment) |
In a small data memory model, the _heapset function is equivalent to the _nheapset function; in a large data memory model, the _heapset function is equivalent to the _fheapset function.
Returns : The _heapset functions return one of the following manifest constants which are defined in <malloc.h>.
| Constant | Meaning |
| _HEAPOK | The heap appears to be consistent. |
| _HEAPEMPTY | The heap is empty. |
| _HEAPBADBEGIN | The heap has been damaged. |
| _HEAPBADNODE | The heap contains a bad node, or is damaged. |
See Also : _heapchk, _heapenable, _heapgrow, _heapmin, _heapshrink, _heapwalk
Example :
#include <stdio.h>
#include <malloc.h>
void main( )
{
int heap_status;
char *buffer;
buffer = (char *) malloc ( 80 );
malloc( 1024 );
free( buffer );
heap_status = _heapset ( 0xff );
switch( heap_status ) {
case _HEAPOK :
printf( "OK - heap is good\n" );
break;
case _HEAPEMPTY :
printf( "OK - heap is empty\n" );
break;
case _HEAPBADBEGIN :
printf( "ERROR - heap is damaged\n" );
break;
case _HEAPBADNODE :
printf( "ERROR - bad node in heap\n" );
break;
}
}
Classification : WATCOM
Systems : _heapset - All
_fheapset - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_nheapset - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT
_bheapset - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
This manual describes the WATCOM C library for DOS, Windows, and OS/2, It includes the Standard C Library (as defined in the ANSI C Standard).
WATCOM C Language Reference manual describes the ANSI C Programming language and extensions to it which are supported by WATCOM C/C++ (32bit)
