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.