# Heap Management in HDF5

    Heap functions are in the H5H package.

    off_t
    H5H_new (hdf5_file_t *f, size_t size_hint, size_t realloc_hint);

    	Creates a new heap in the specified file which can efficiently
    	store at least SIZE_HINT bytes.  The heap can store more than
    	that, but doing so may cause the heap to become less efficient
    	(for instance, a heap implemented as a B-tree might become
    	discontigous).  The REALLOC_HINT is the minimum number of bytes
    	by which the heap will grow when it must be resized. The hints
    	may be zero in which case reasonable (but probably not
    	optimal) values will be chosen.

    	The return value is the address of the new heap relative to
    	the beginning of the file boot block.

    off_t
    H5H_insert (hdf5_file_t *f, off_t addr, size_t size, const void *buf);

    	Copies SIZE bytes of data from BUF into the heap whose address
    	is ADDR in file F.  BUF must be the _entire_ heap object.  The
    	return value is the byte offset of the new data in the heap.

    void *
    H5H_read (hdf5_file_t *f, off_t addr, off_t offset, size_t size, void *buf);

    	Copies SIZE bytes of data from the heap whose address is ADDR
    	in file F into BUF and then returns the address of BUF.  If
    	BUF is the null pointer then a new buffer will be malloc'd by
    	this function and its address is returned.

    	Returns buffer address or null.

    const void *
    H5H_peek (hdf5_file_t *f, off_t addr, off_t offset)

    	A more efficient version of H5H_read that returns a pointer
    	directly into the cache; the data is not copied from the cache
    	to a buffer.  The pointer is valid until the next call to an
    	H5AC function directly or indirectly.

    	Returns a pointer or null.  Do not free the pointer.

    void *
    H5H_write (hdf5_file_t *f, off_t addr, off_t offset, size_t size,
               const void *buf);

    	Modifies (part of) an object in the heap at address ADDR of
    	file F by copying SIZE bytes from the beginning of BUF to the
    	file.  OFFSET is the address withing the heap where the output
    	is to occur.

    	This function can fail if the combination of OFFSET and SIZE
    	would write over a boundary between two heap objects.

    herr_t
    H5H_remove (hdf5_file_t *f, off_t addr, off_t offset, size_t size);

    	Removes an object or part of an object which begins at byte
    	OFFSET within a heap whose address is ADDR in file F.  SIZE
    	bytes are returned to the free list.  Removing the middle of
    	an object has the side effect that one object is now split
    	into two objects.

    	Returns success or failure.

    ===========================================
    Last Modified:  8 July 1998 (technical content)
    Last Modified:  28 April 2000 (included in HDF5 Technical Notes)
    HDF Help Desk:  hdfhelp@ncsa.uiuc.edu