heap.man

一个堆栈管理器的源码

               under _HEAPDEBUG, after ever heap transaction it reports the
               nature of the transaction, its source-code location, and the
               values of the arguments and returned result. 
 

    Further info

        See page 347 of the MSC 5.1 Optimizing Compiler Run-Time Reference


_HEAPCHK

    Summary

        #include <heap.h>

        int _heapchk( void );


    Differences

        In "small" and "medium" model programs _heapchk comes from the
        original library.  In "compact", "large", and "huge" model
        programs _heapchk comes from the replacement library, and differs
        from the original in the following ways:

            1. It performs a detailed consistency check on each heap
               entry, verifying the validity of the heap control block
               and checking its neighbors for reciprocity.

            2. The safety margins controlled by _heappad are inspected
               for changes.  Any alteration of the safety margins
               produces a _HEAPBADPTR result code.

            3. The checksums on the read-only heap entries established
               by _fheapwatch are recalculated.  A changed checksum
               produces a _HEAPBADPTR result code


    Further info

        See page 352 of the MSC 5.1 Optimizing Compiler Run-Time Reference


_HEAPSET


    Summary

        #include <heap.h>

        int _heapset( fill );
        uint fill;                      // Value to fill with


    Differences

        In "small" and "medium" model programs _heapset comes from the
        original library.  In "compact", "large", and "huge" model
        programs _heapset comes from the replacement library, and differs
        from the original in the following ways:

            1. It performs a detailed consistency check on each heap
               entry, verifying the validity of the heap control block
               and checking its neighbors for reciprocity.

            2. The safety margins controlled by _heappad are inspected
               for changes.  Any alteration of the safety margins
               produces a _HEAPBADPTR result code.

            3. The checksums on the read-only heap entries established
               by _fheapwatch are recalculated.  A changed checksum
               produces a _HEAPBADPTR result code

            4. The default safety margin fill value is reset by each call
               to _heapset.


    Further info

        See page 354 of the MSC 5.1 Optimizing Compiler Run-Time Reference


_HEAPSTAT

    Summary

        #include <heap.h>

        #if !defined( STDMSC )

        char *_heapstat( status )
        int status;                     // Status code from _heapchk/set/walk

        #endif


    Description

        The _heapstat function translates heap status codes into descriptive
        strings.  Invalid status codes are also reported as such.

        The translation is as follows:

            _HEAPEMPTY      Heap not initialized

            _HEAPOK         Heap is OK

            _HEAPBADBEGIN   Master heap data corrupt

            _HEAPBADNODE    Bad heap control block

            _HEAPEND        End of heap

            _HEAPBADPTR     Bad pointer or data corrupted

            all others      Unknown heap status code


    Differences

        The _heapstat function is unique to the replacement heap manager.


    Return Value

        The _heapstat function returns a pointer to the string containing
        the status message.


    See Also

        _fheapchk, _fheapset, _fheapwalk, _heapchk, _heapset, _heapwalk


    Example

        #include <stdio.h>

        #include <heap.h>

        int main()
        {
        printf("Heap status : %s\n", _heapstat( _heapchk() ) );

        malloc( 1234 );

        printf("Heap status : %s\n", _heapstat( _heapchk() ) );

        return( 0 );
        }

        This program checks the heap status before and after the heap is
        initialized.  If the heap is not consistent it prints out
        a error message.


_HEAPWALK

    Summary

        #include <heap.h>

        int _heapwalk( info );
        struct _heapinfo *info;         // Info on one heap entry


    Differences

        In "small" and "medium" model programs _heapwalk comes from the
        original library.  In "compact", "large", and "huge" model
        programs _heapwalk comes from the replacement library, and differs
        from the original in the following ways:

            1. It performs a detailed consistency check on each heap
               entry, verifying the validity of the heap control block
               and checking its neighbors for reciprocity.

            2. The safety margins controlled by _heappad are inspected
               for changes.  Any alteration of the safety margins
               produces a _HEAPBADPTR result code.

            3. The checksums on the read-only heap entries established
               by _fheapwatch are recalculated.  A changed checksum
               produces a _HEAPBADPTR result code


    Further info

        See page 356 of the MSC 5.1 Optimizing Compiler Run-Time Reference


_HEXPAND

    Summary

        #include <heap.h>

        #if !defined( STDMSC )

        void far *_hexpand( buffer, size );
        void far *buffer;               // Pointer to memory block
        long      size;                 // Desired number of bytes

        #endif

        #if !defined( STDMSC ) && !defined( NDEBUG )

        void far *_hexpand_c( buffer, size, file, line, stream );  // check pointers
        void far *_hexpand_d( buffer, size, file, line, stream );  // debug
        void far *_hexpand_t( buffer, size, file, line, stream );  // trace
        void far  *buffer;              // Pointer to memory block
        long       size;                // Desired number of bytes
        char near *file;                // Name of source file (__FILE__)
        uint       line;                // Source file line number (__LINE__)
        FILE      *stream;              // Error output file

        #endif


    Description

        The _hexpand function is a proper superset of the _expand function.
        It adjusts "far" and "huge" blocks in the same way _expand adjusts
        "far" blocks.

        The _hexpand function adjusts the size of an existing heap entry,
        used or free, without moving the block.  Invalid pointers are
        ignored by hexpand, which returns NULL when one is detected.

        The alternate forms of _hexpand are controlled as follows:

            1. The _HEAPCHECK symbol enables the pointer checking
               alternate version of _hexpand, which reports invalid
               pointers, detailing the location of the offending
               function in the source code.

            2. The _HEAPDEBUG symbol enables the debugging alternate
               version of _hexpand.  In addition to the pointer checking
               described under _HEAPCHECK, prior to every heap access it
               checks the heap status via _fheapchk, and reports errors
               on the indicated stream file with _heapdump.
               
            3. The _HEAPTRACE symbol enables the tracing alternate
               version of _hexpand.  In addition to the debugging described
               under _HEAPDEBUG, after every heap transaction it reports the
               nature of the transaction, its source-code location, and the
               values of the arguments and the returned result. 
 

    Return Value

        The _hexpand function returns a pointer to the adjusted entry.  If
        the adjustment failed or the pointer argument is invalid _hexpand
        returns NULL.

        If there is not enough memory to meet the desired size the heap
        entry will be expanded to the limit of available memory.
        

    Differences

        The _hexpand function is unique to the replacement heap manager.


    See Also

        _expand, _fmsize, _frelocate, halloc, hfree, _hmsize, hrealloc


    Further info

        See page 346 of the MSC 5.1 Optimizing Compiler Run-Time Reference



HFREE

    Summary

        #include <heap.h>

        void hfree( buffer );
        void huge *buffer;              // Pointer to memory block

        #if !defined( STDMSC ) && !defined( NDEBUG )

        void hfree_c( buffer, file, line, stream );  // check pointers
        void hfree_d( buffer, file, line, stream );  // debug
        void hfree_t( buffer, file, line, stream );  // trace
        void huge *buffer;              // Pointer to memory block
        char near *file;                // Name of source file (__FILE__)
        uint       line;                // Source file line number (__LINE__)
        FILE      *stream;              // Error output file

        #endif


    Differences
    
        The replacement version of hfree differs from the original
        in the following ways:

            1. The hfree function is identical to the _ffree function.
               It releases memory back to the "far" heap rather than to DOS.
               Hfree can handle the results of any of the "far" heap
               management functions.

            2. Invalid pointers are ignored by hfree.

            3. The _HEAPCHECK symbol enables the pointer checking
               alternate version of hfree, which reports invalid
               pointers, detailing the location of the offending
               function in the source code.

            4. The _HEAPDEBUG symbol enables the debugging alternate
               version of hfree.  In addition to the pointer checking
               described under _HEAPCHECK, prior to every heap access it
               checks the heap status via _fheapchk, and reports errors
               on the indicated stream file with _heapdump.
               
            5. The _HEAPTRACE symbol enables the tracing alternate
               version of hfree.  In addition to the debugging described
               under _HEAPDEBUG, after every heap transaction it reports the
               nature of the transaction, its source-code location, and the
               values of the arguments and the returned result. 
 


    Further info

        See page 359 of the MSC 5.1 Optimizing Compiler Run-Time Reference


_HMSIZE

    Summary

        #include <heap.h>


        #if !defined( STDMSC )

        long _hmsize( buffer );
        void huge *buffer;              // Pointer to memory block

        #endif

        #if !defined( STDMSC ) && !defined( NDEBUG )

        long _hmsize_c( buffer, file, line, stream );    // check pointers
        void huge *buffer;              // Pointer to memory block
        long       size;                // Desired number of bytes
        char near *file;                // Name of source file (__FILE__)
        uint       line;                // Source file line number (__LINE__)
        FILE      *stream;              // Error output file

        #endif


    Description

        The _hmsize function is a proper superset of the _fmsize function.
        It reports "far" and "huge" blocks in the same way _fmsize reports
        "far" blocks.

        The _hmsize function returns the size, as a long integer, of the
        indicated heap entry.  NULL pointers have size zero, as do
        invalid pointers.

        The _HEAPCHECK symbol enables the pointer checking alternate
        version of _hms