Watcom C Library : _heapshrink Functions, _heapwalk Functions, hfree, hypot
Watcom C Reference/G - H - I 2021. 6. 30. 21:45
Watcom C Library Reference : _heapshrink Functions, _heapwalk Functions, hfree, hypot
_heapshrink Functions
Synopsis : #include <malloc.h>
int _heapshrink( void );
int _bheapshrink( __segment seg );
int fheapshrink( void );
int _nheapshrink( void );
Description : The _heapshrink functions attempt to shrink the 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 _heapshrink functions shrink the following heaps:
| Function | Heap Shrinked |
| _heapshrink | Depends on data model of the program |
| _bheapshrink | Based heap specified by seg value; _NULLSEG specifies all based heaps |
| _fheapshrink | Far heap (outside the default data segment) |
| _nheapshrink | Near heap (inside the default data segment) |
In a small data memory model, the _heapshrink function is equivalent to the _nheapshrink function; in a large data memory model, the _heapshrink function is equivalent to the _fheapshrink function. It is identical to the _heapmin function.
Returns : These functions return zero if successful, and non-zero if some error occurred.
See Also : _heapchk, _heapenable, _heapgrow, _heapmin, _heapset, _heapwalk
Example :
#include <stdlib.h>
#include <malloc.h>
void main( )
{
_heapshrink( );
system( "chdir c:\\watcomc" );
}
Note the use of two adjacent backslash characters (\) within character-string constants to signify a single backslash.
Classification : WATCOM
Systems : _heapshrink - All
_bheapshrink - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_fheapshrink - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_nheapshrink - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT
_heapwalk Functions
Synopsis : #include <malloc.h>
int _heapwalk( struct _heapinfo *entry );
int _bheapwalk( __segment seg, struct _heapinfo *entry );
int _fheapwalk( struct _heapinfo *entry );
int _nheapwalk( struct _heapinfo *entry );
struct _heapinfo {
void __far *_pentry; /* heap pointer */
size_t size; /* heap entry size */
int _useflag; /* heap entry 'in-use' flag */
};
#define _USEDENTRY 0
#define _FREEENTRY 1
Description : The _heapwalk functions along with _heapchk and _heapset are provided for debugging heap related problems in programs.
The _heapwalk functions walk through the heap, one entry per call, updating the _heapinfo structure with information on the next heap entry. The structure is defined in <malloc.h>. You must initialize the _pentry field with NULL to start the walk through the heap.
Each function walks a particular heap, as listed below:
| Function | Heap Walked |
| _heapwalk | Depends on data model of the program |
| _bheapwalk | Based heap specified by seg value; _NULLSEG specifies all based heaps |
| _fheapwalk | Far heap (outside the default data segment) |
| _nheapwalk | Near heap (inside the default data segment) |
In a small data memory model, the _heapwalk function is equivalent to the _nheapwalk function; in a large data memory model, the _heapwalk function is equivalent to the _fheapwalk function.
Returns : These functions return one of the following manifest constants which are defined in <malloc.h>.
| Constant | Meaning |
| _HEAPOK | The heap is OK so far, and the _heapinfo structure contains information about the next entry in the heap. |
| _HEAPEMPTY | The heap is empty. |
| _HEAPBADPTR | The _pentry field of the entry structure does not contain a valid pointer into the heap. |
| _HEAPBADBEGIN | The header information for the heap was not found or has been damaged. |
| _HEAPBADNODE | The heap contains a bad node, or is damaged. |
| _HEAPEND | The end of the heap was reached successfully. |
See Also : _heapchk, _heapenable, _heapgrow, _heapmin, _heapset, _heapshrink
Example :
#include <stdio.h>
#include <malloc.h>
heap_dump( )
{
struct _heapinfo h_info;
int heap_status;
h_info._pentry = NULL;
for ( ; ; ) {
heap_status = _heapwalk( &h_info );
if( heap_status != _HEAPOK ) break;
printf( " %s block at %Fp of size %4.4x\n",
(h_info._useflag == _USEDENTRY ? "USED" : "FREE"),
h_info._pentry, h_info._size );
}
switch ( heap_status) {
case _HEAPEND :
printf( "OK - end of heap\n" );
break;
case _HEAPEMPTY :
printf( "OK - heap is empty\n" );
break;
case _HEAPBADBEGIN :
printf( "ERROR - heap is damaged\n" );
break;
case _HEAPBADPTR :
printf( "ERROR - bad pointer to heap\n" );
break;
case _HEAPBADNODE :
printf( "ERROR - bad node in heap\n" );
}
}
void main( )
{
char *p;
heap_dump( );
p = (char *) malloc( 80 );
heap_dump( );
free( p );
heap_dump( );
}
produces the following :
On 16-bit 80x86 systems, the following output is produced :
OK - heap is empty
USED block at 23f8:0ab6 of size 0202
USED block at 23f8:0cb8 of size 0052
FREE block at 23f8:0d0a of size 1DA2
OK - end of heap
USED block at 23f8:0ab6 of size 0202
FREE block at 23f8:0cb8 of size 1DF4
OK - end of heap
On 32-bit 80386/486 systems, the following output is produced :
OK - heap is empty
USED block at 0014:00002a7c of size 0204
USED block at 0014:00002c80 of size 0054
FREE block at 0014:00002cd4 of size 1D98
OK - end of heap
USED block at 0014:00002a7c of size 0204
FREE block at 0014:00002c80 of size 1DEC
OK - end of heap
Classification : WATCOM
Systems : _heapwalk - All
_bheapwalk - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_fheapwalk - DOS/16, Win/16, QNX/16, OS/2 1.x(all)
_nheapwalk - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT
hfree
Synopsis : #include <malloc.h>
void hfree( void __huge *ptr );
Description : The hfree function deallocates a memory block previously allocated by the halloc function. The argument ptr points to a memory block to be deallocated. After the call, the freed block is available for allocation.
Returns : The hfree function returns no value.
See Also : calloc Functions, _expand Functions, free Functions, halloc, malloc Functions, _msize Functions, realloc Functions, sbrk
Example :
#include <stdio.h>
#include <malloc.h>
void main( )
{
long int __huge *big_buffer;
big_buffer = ( long int __huge * ) halloc ( 1024L, sizeof( long) );
if( big_buffer == NULL ) {
printf( "Unable to allocate memory\n" );
} else {
/* rest of code goes here */
hfree ( big_buffer ); /* deallocate */
}
}
Classification : WATCOM
Systems : DOS/16, Win/16, QNX/16, OS/2 1.x(all)
hypot
Synopsis : #include <math.h>
double hypot( double x, double y );
Description : The hypot function computes the length of the hypotenuse of a right triangle whose sides are x and y adjacent to that right angle. The calculation is equivalent to
sqrt( x*x + y*y )
The computation may cause an overflow, in which case the matherr function will be invoked.
Returns : The value of the hypotenuse is returned. When an error has occurred, errno contains a value indicating the type of error that has been detected.
Example :
#include <stdio.h>
#include <math.h>
void main( )
{
printf( "%f\n", hypot ( 3.0, 4.0 ) ) ;
}
produces the following :
5.000000
Classification : WATCOM
Systems : 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)
