Memory Management

Reference Section

_far_avail
_far_calloc
_far_free
_far_malloc
_far_max
_far_realloc
fheap_dosmin
fheap_len
fheap_size
fheap_start
_near_avail
_near_calloc
_near_free
_near_malloc
_near_max
_near_realloc
nheap_comlen
nheap_len
nheap_size
nheap_start
_rel_avail
_rel_calloc
_rel_free
_rel_init
_rel_malloc
_rel_max
_rel_realloc

_far_avail


Descrip
Returns the number of available bytes on the far heap.

Syntax
#include <memalloc.h>
long int _far_avail(void);

Returns
The number of available bytes on the far heap.

Notes
This function returns the total number of available bytes on the far heap. The return value is zero if the far heap is full or if the far heap is uninitialized.

See the Memory Management technical notes for special installation instructions that must be followed prior to using this function.

C/C++ Example
	{
	   void far *block;
	   long int heap_left;
	   block = (char *)_far_malloc(0x400);
	   heap_left = _far_avail ();
	   _far_free(block);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void far *buffer;
	   ...
	   buffer = (char *)_far_malloc (0x400);
	   far_avail();/* DX;AX = bytes left on heap */
	   ...
	   _far_free(buffer);
	}

Source file MAFAVAIL.ASM ASM equiv FAR_AVAIL
See also
_far_avail, _far_max, _near_avail, _rel_avail

_far_calloc


Descrip
Allocates space for a specified number of objects on the far heap and sets all allocated bytes to zero.

Syntax
#include <memalloc.h>
void far *_far_calloc(int num, long int size);

Returns
A pointer to the newly allocated block of memory.

NULL if num times size bytes could not be allocated.

Notes
This function allocates a paragraph-aligned block on the far heap and returns a pointer to that block. The newly allocated block is num times size bytes in size; a maximum of 524,270 bytes may be allocated in one block. Each byte in the allocated block is cleared (set to zero). NULL is returned if num times size bytes cannot be allocated.

This function initializes the far heap if the far heap has not already been initialized. In SMALL data models this function also initializes the near heap if needed. The fheap_len and fheap_dosmin variables are used to control the size of the far heap; the nheap_len and nheap_comlen variables are used to control the size of the near heap.

See the Memory Management technical notes for special installation instructions that must be followed prior to using this function.

WARNING! If num or size is zero, a valid block pointer is returned even though the block may have zero bytes of available space. Any attempt to write past the end of a block may corrupt the heap.

C/C++ Example
	{
	   char far *fblk;
	   ...
	   fblk = (char *)_far_calloc(20,1); /* allocate a block and
	   	  	 	    initialize to 0 */
	   _fstr_cpy(fblk, "hello\n\r");/* copy string to far block */
	   _fput_str(fblk);/* display string from far block */
	   ...
	}

Inline Assembly Example
	Because of variations between compilers, an inline version
	   of this function has not been provided.

Source file _MAFCALC.ASM ASM equiv FAR_CALLOC
See also
_far_free, _far_init, _far_malloc, _far_max, _far_realloc, _near_calloc, _rel_calloc

_far_free


Descrip
Frees a block on the far heap.

Syntax
#include <memalloc.h>
int _far_free(void far *block);

Returns
0 if block was successfully released.

-1 if block is invalid or the far heap is uninitialized.

Notes
This function releases the memory block at block on the far heap, making its memory available for future allocation. block must be a valid memory block pointer obtained by calling _far_malloc, _far_calloc, or _far_realloc. -1 is returned if block is invalid or if the far heap is not initialized.

See the Memory Management technical notes for special installation instructions that must be followed prior to using this function.

WARNING! Only limited checking is performed to detect an invalid block. If an attempt is made to free a block using an invalid block value and -1 is not returned, the heap may be corrupted.

C/C++ Example
	{
	   void far *pointer;
	   ...
	   pointer = (char *)_far_malloc (0x10);
	   if (pointer == NULL)    /* allocate 16 byte block */
	   {
	      /* handle the error */
	   } 
	   ...
	   if (_far_free (pointer) == -1) /* free block */
	   {
	      /* handle the error */
	   }
	}

Inline Assembly Example
	Because of variations between compilers, an inline version
	   of this function has not been provided.

Source file _MAFFREE.ASM ASM equiv FAR_FREE
See also
_far_calloc, _far_init, _far_malloc, _far_realloc, _near_free, _rel_free

_far_malloc


Descrip
Allocates a specified number of bytes on the far heap.

Syntax
#include <memalloc.h>
void far *_far_malloc(long int num);

Returns
A pointer to the allocated block on the far heap.

NULL if num bytes could not be allocated.

Notes
This function allocates a paragraph-aligned block of num bytes on the far heap. A maximum of 524,270 bytes may be allocated in one block. A pointer to the newly allocated block is returned. A NULL is returned if num bytes cannot be allocated.

This function initializes the far heap if the far heap has not already been initialized. In SMALL data models this function also initializes the near heap if needed. The fheap_len and fheap_dosmin variables are used to control the size of the far heap; the nheap_len and nheap_comlen variables are used to control the size of the near heap.

See the Memory Management technical notes for special installation instructions that must be followed prior to using this function.

WARNING! If num is zero, a valid block pointer is returned even though the block may have zero bytes of available space. Any attempt to write past the end of a block may corrupt the heap.

C/C++ Example
	{
	   char far *fblk;
	   ...
	   fblk = (char far *)_far_malloc(20);/* allocate far block */
	   _fstr_cpy(fblk, "hello\n\r");/* copy string to far block */
	   _fput_str(fblk);	/* display str from far block */
	   ...
	}

Inline Assembly Example
	Because of variations between compilers, an inline version
	   of this function has not been provided.

Source file _MAFMALC.ASM ASM equiv FAR_MALLOC
See also
_dos_malloc, _far_calloc, _far_init, _far_max, _far_realloc, _near_malloc, _rel_malloc

_far_max


Descrip
Returns the size of the largest available block on the far heap.

Syntax
#include <memalloc.h>
long int _far_max(void);

Returns
The size of the largest available block on the far heap, in bytes.

Notes
This function returns the number of bytes in the largest available block on the far heap. 0 is returned if no space is available or the far heap is uninitialized.

See the Memory Management technical notes for special installation instructions that must be followed prior to using this function.

C/C++ Example
	{
	   void far *block;
	   long int heap_largest;
	   block = (char *)_far_malloc (0x400);
	   heap_largest = _far_max ();
	   ...
	   _far_free (block);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void far *buffer;
	   ...
	   buffer = (char *)_far_malloc (0x400);
	   far_max();/* DX;AX = largest block avail */
	   ...
	   _far_free(buffer);
	}

Source file None ASM equiv FAR_MAX
See also
_far_avail, _far_init, _near_max, _rel_max

_far_realloc


Descrip
Alters the size of a far heap memory block.

Syntax
#include <memalloc.h>
void far *_far_realloc(void far *block, long int num);

Returns
A pointer to the resized block of memory if the block was successfully resized.

NULL if the block could not be reallocated to num bytes.

Notes
This function attempts to shrink or grow the memory block at block on the far heap so that it becomes num bytes in size. If the block at block cannot be resized directly, a new block of the requested size is allocated and the contents of the first block are copied into the second block. block must be a valid memory block pointer obtained by calling _far_malloc, _far_calloc, or _far_realloc. A maximum of 524,270 bytes may be allocated in one block. If successful a pointer to the resulting block is returned. NULL is returned if num bytes cannot be allocated, block is an invalid memory block pointer, or if the far heap is not initialized.

See the Memory Management technical notes for special installation instructions that must be followed prior to using this function.
WARNING! Only limited checking is performed to detect an invalid block. If an attempt is made to resize a block using an invalid block pointer and NULL is not returned, the heap may be corrupted.

WARNING! If num is zero, a valid pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block may corrupt the heap.

C/C++ Example
	{
	   void far *pointer, far *extra_ptr;
	   pointer = _far_malloc(0x10);/* allocate 16 byte block */
	   if (pointer == NULL)
	   {
	      /* error allocating block */
	   }
	   ...
	   extra_ptr = _far_realloc (pointer, 0x20);
	   	  	 	/* reallocate block to 32 bytes */
	   if (extra_ptr == NULL)
	   {
	      /* error allocating block */
	   }
	   pointer = extra_ptr;    /* reassign block pointer */
	   ... 
	}

Inline Assembly Example
	Because of variations between compilers, an inline version
	   of this function has not been provided.

Source file _MAFRALC.ASM ASM equiv FAR_REALLOC
See also
_far_calloc, _far_init, _far_malloc, _far_max, _near_realloc, _rel_realloc

fheap_dosmin


Descrip
(Variable) Indicates the minimum number of paragraphs to leave available for DOS when the far heap is initialized.

Syntax
#include <memalloc.h>
unsigned int fheap_dosmin;

Notes
This unsigned int variable specifies the minimum number of paragraphs to leave available to DOS when the far heap is initialized. The fheap_dosmin variable always takes precedence over the fheap_len variable. The default value for fheap_dosmin is 0. If another value is needed, the fheap_dosmin variable must be set before the far heap is initialized. For example:

/* leave 4096 paragraphs (64K) for DOS when far heap is initialized */
externunsigned fheap_dosmin = 4096;
main ()
{
...
}

The first call to malloc or calloc in the LARGE data models or the first call to _far_malloc or _far_calloc in any memory model initializes the far heap.

See the Memory Management technical notes for special installation instructions that must be followed prior to using the Spontaneous Assembly far heap management functions.

Source file _MACVARS.ASM ASM equiv None
See also
fheap_len, fheap_size, fheap_start

fheap_len


Descrip
(Variable) Indicates the maximum size of the far heap, in paragraphs.

Syntax
#include <memalloc.h>
extern unsigned int fheap_len;

Notes
This unsigned int variable specifies the maximum size of the far heap, in paragraphs. This value is only used when the far heap is initialized. The default value for fheap_len is -1, which initializes the far heap to its largest possible size (minus fheap_dosmin paragraphs). If another value is needed, the fheap_len variable must be set before the far heap is initialized. For example:

/* initialize far heap to 8192 paragraphs (128K) */
externunsigned fheap_len = 8192;
main ()
{
...
}

The first call to malloc or calloc in the LARGE data models or the first call to _far_malloc or _far_calloc in any memory model initializes the far heap.

See the Memory Management technical notes for special installation instructions that must be followed prior to using the Spontaneous Assembly far heap management functions.

Source file _MACVARS.ASM ASM equiv None
See also
fheap_dosmin, fheap_size, fheap_start

fheap_size


Descrip
(Variable) Indicates the current size of the far heap.

Syntax
#include <memalloc.h>
unsigned int fheap_size;

Notes
This unsigned int variable contains the current size of the far heap, in paragraphs. A size of zero indicates that the far heap is not initialized.

Source file MAVARS.ASM ASM equiv FHEAP_SIZE
See also
fheap_dosmin, fheap_len, fheap_start

fheap_start


Descrip
(Variable) Contains the starting segment of the far heap.

Syntax
#include <memalloc.h>
extern segaddr fheap_start;

Notes
This unsigned int variable indicates the starting segment of the far heap if the far heap is initialized. This variable is undefined if the far heap is not initialized. If fheap_size is 0, the far heap is not initialized.

Source file MAVARS.ASM ASM equiv FHEAP_START
See also
fheap_dosmin, fheap_len, fheap_size

_near_avail


Descrip
Returns the number of available bytes on the near heap.

Syntax
#include <memalloc.h>
unsigned int _near_avail(void);

Returns
The number of available bytes on the near heap.

Notes
This function returns the total number of available bytes on the near heap. 0 is returned if the near heap is full or if the near heap is uninitialized.

See the technical notes for special installation instructions which must be followed prior to using this function.

C/C++ Example
	{
	   void *block;
	   unsigned int heap_left;
	   block = _near_malloc(0x400);
	   heap_left = _near_avail();
	   _near_free(block);
	}

Inline Assembly Example
	#include <inline.h>
	{
	void *block;
	   ...
	   block = _near_malloc(0x400); /* AX -> allocated block */
	   near_avail();/* AX = number of bytes available */
	   ...
	   _near_free (block);
	   ...
	}

Source file MANAVAIL.ASM ASM equiv NEAR_AVAIL
See also
_far_avail, _near_max, _rel_avail

_near_calloc


Descrip
Allocates space for a specified number of objects on the near heap and sets all allocated bytes to zero.

Syntax
#include <memalloc.h>
void near *_near_calloc(int num, int size);

Returns
A pointer to the allocated block on the near heap if a block of num times size bytes was successfully allocated.

NULL if num times size bytes could not be allocated.

Notes
This function allocates a word-aligned block on the near heap and returns a near pointer to that block. The newly allocated block is num times size bytes in size. A maximum of 32,764 bytes may be allocated in one block. Each allocated byte is cleared to zero. NULL is returned if num times size bytes cannot be allocated. The near heap is not available in large data models.

This function initializes the near heap if the near heap has not already been initialized. The nheap_len and nheap_comlen variables are used to control the size of the near heap.

See the technical notes for special installation instructions that must be followed prior to using this function.

WARNING! If num or size is zero, a valid block pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block will corrupt the heap.

C/C++ Example
	{
	   char * nblk;
	   ...
	   nblk = (char *)_near_calloc(20,1); /* allocate a block and
	   	  	 	    initialize to 0 */
	   _str_cpy(nblk, "hello\n\r");/* copy string to block */
	   _put_str(nblk);	/* display string in block */
	   ...
	}

Inline Assembly Example
	Because of variations between compilers, an inline version
	   of this function has not been provided.

Source file _MANCALC.ASM ASM equiv NEAR_CALLOC
See also
_far_calloc, _near_free, _near_malloc, _near_max, _near_realloc, _rel_calloc

_near_free


Descrip
Frees a block on the near heap.

Syntax
#include <memalloc.h>
int _near_free(void near *block);

Returns
0 if the block was successfully released.

-1 if the function was unsuccessful.

Notes
This function releases the block at block on the near heap, freeing its memory for future allocation. block must be a valid block pointer obtained by calling _near_malloc, _near_calloc, or _near_realloc. -1 is returned if block is invalid or if the near heap is not initialized. The near heap is not available in large data models.

See the technical notes for special installation instructions that must be followed prior to using this function.

WARNING! Only limited checking is performed to detect an invalid block. If an attempt is made to free a block using an invalid block pointer and -1 is not returned, the heap may be corrupted.

C/C++ Example
	{
	   void *pointer;
	   ...
	   pointer = _near_malloc(0x100); /* allocate 100 bytes */
	   if (pointer == NULL)
	   {
	      /* handle the error */
	   }
	   ... 
	   if (_near_free(pointer) == -1)
	   	  	 /* free block pointer to by pointer */
	   {
	      /* handle the error */
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	Because of variations between compilers, an inline version
	   of this function has not been provided.

Source file _MANFREE.ASM ASM equiv NEAR_FREE
See also
_far_free, _near_calloc, _near_malloc, _near_realloc, _rel_free

_near_malloc


Descrip
Allocates a specified number of bytes on the near heap.

Syntax
#include <memalloc.h>
void near *_near_malloc(int num);

Returns
A pointer to the allocated block on the near heap if a block of num bytes was successfully allocated.

NULL if num bytes could not be allocated.

Notes
This function allocates a word-aligned block of num bytes on the near heap and returns a near pointer to that block. A maximum of 32,764 bytes may be allocated in one block. NULL is returned if num bytes cannot be allocated. The near heap is not available in large data models.

This function initializes the near heap if the near heap has not already been initialized. The nheap_len and nheap_comlen variables are used to control the size of the near heap.

See the technical notes for special installation instructions that must be followed prior to using this function.

WARNING! If num is zero, a valid block pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block will corrupt the heap.

C/C++ Example
	{
	   char *nblk;
	   ...
	   nblk = (char *)_near_malloc(20);/* allocate a block */
	   _str_cpy(nblk, "hello\n\r");	  /* copy string */
	   _put_str(nblk);	    /* display block */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	Because of the variations between compilers, an inline version
	   of this function has not been provided.

Source file _MANMALC.ASM ASM equiv NEAR_MALLOC
See also
_dos_malloc, _far_malloc, _near_calloc, _near_max, _near_realloc, _rel_malloc

_near_max


Descrip
Returns the size of the largest available block on the near heap.

Syntax
#include <memalloc.h>
unsigned int _near_max(void);

Returns
The size, in bytes, of the largest available block on the near heap.

Notes
This function returns the number of bytes in the largest available block on the near heap. 0 is returned if no space is available or the near heap is uninitialized.

See the technical notes for special installation instructions that must be followed prior to using this function.

C/C++ Example
	{
	   void *block;
	   unsigned int heap_largest;
	   block = _near_malloc(0x400);
	   heap_largest = _near_max();
	   _near_free(block);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   void *block;
	   ...
	   block = _near_malloc(0x400); /* AX -> allocated block */
	   near_max();	    /* AX = size of largest block */
	   ...
	     _near_free(block);
	}

Source file MANMAX.ASM ASM equiv NEAR_MAX
See also
_far_free, _near_calloc, _near_malloc, _near_realloc, _rel_free

_near_realloc


Descrip
Alters the size of a near heap memory block.

Syntax
#include <memalloc.h>
void near *_near_realloc(void near *block, int num);

Returns
A pointer to the resized block if block was successfully resized.

NULL if the block could not be resized.

Notes
This function attempts to shrink or grow the block at block on the near heap so that it becomes num bytes in size. If the block at block cannot be resized directly, a new block of the requested size is allocated and the contents of the first block are copied into the second block. block must be a valid block offset obtained by calling _near_malloc, _near_calloc, or _near_realloc. A maximum of 32,764 bytes may be allocated in one block. A near pointer to the resulting block is returned. NULL is returned if num bytes cannot be allocated, block is an invalid block offset, or if the near heap is not initialized. The near heap is not available in large data models.

See the technical notes for special installation instructions that must be followed prior to using this function.

WARNING! Only limited checking is performed to detect an invalid block. Any attempt to resize a block using an invalid block may corrupt the heap if NULL is not returned.

WARNING! If num is zero, a valid block pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block will corrupt the heap.

C/C++ Example
	{
	   void *block, *extra_blk;
	   ...
	   block = _near_malloc(0x100); /*allocate a block of 100 bytes*/
	   if (block == NULL)
	   {
	      /* error allocating block */
	   }
	   ...
	   extra_blk = _near_realloc(block, 0x200);
	   if (extra_blk == NULL)
	   {
	      /* error resizing block */
	   }
	   ... 
	   block = extra_blk;/* reassign block pointer */
	}

Inline Assembly Example
	#include <inline.h>
	Because of the variations between compilers, an inline version
	   of this function has not been provided.

Source file _MANRALC.ASM ASM equiv NEAR_REALLOC
See also
_far_realloc, _near_calloc, _near_malloc, _near_max, _rel_realloc

nheap_comlen


Descrip
(Variable) Indicates the minimum number of bytes to leave available for the .COM stack when the near heap is initialized (TINY model only).

Syntax
#include <memalloc.h>
extern unsigned int nheap_comlen;

Notes
This unsigned int variable determines the number of bytes to leave for the .COM stack in the TINY data model. The near heap will be initialized between the end of static data in @DATASEG and the .COM stack.

The default value for nheap_comlen is 1000, which leaves 1000 bytes for the .COM stack. The nheap_comlen global variable may be modified as follows:

/* leave 2500 bytes for .COM stack when near heap is initialized */
externunsigned nheap_comlen = 2500;
main ()
{
...
}

The first call to malloc, calloc, _near_malloc, _near_calloc, _far_malloc, or _far_calloc initializes the near heap in small data models. The near heap is not available in large data models.

See the Memory Management technical notes for special installation instructions that must be followed prior to using the Spontaneous Assembly near heap management functions.

Source file _MACVARS.ASM ASM equiv None
See also
_near_calloc, _near_malloc, nheap_len

nheap_len


Descrip
(Variable) Indicates the maximum size of the near heap, in bytes (small data models only).

Syntax
#include <memalloc.h>
extern unsigned int nheap_len;

Notes
This unsigned int variable determines the size (in bytes) of the near heap in small data models only. The near heap is not available in large data models.

The default value for nheap_len is -1, which initializes the near heap to its largest possible size (minus nheap_comlen bytes in the TINY model). The nheap_len global variable may be modified as follows:

/* initialize a 10,000 byte near heap */
externunsigned nheap_len = 10000;
main ()
{
...
}

The first call to malloc, calloc, _near_malloc, _near_calloc, _far_malloc, or _far_calloc initializes the near heap in small data models.

See the Memory Management technical notes for special installation instructions that must be followed prior to using the Spontaneous Assembly near heap management functions.

Source file _MACVARS.ASM ASM equiv None
See also
_near_malloc, _near_calloc, nheap_comlen

nheap_size


Descrip
(Variable) Indicates the current size of the near heap.

Syntax
#include <memalloc.h>
extern unsigned int nheap_size;

Syntax
#include <memalloc.h>
extern unsigned nheap_size;

Notes
This unsigned int variable contains the current size of the near heap, in bytes. A size of zero indicates that the near heap is not initialized.

Source file MAVARS.ASM ASM equiv NHEAP_SIZE

nheap_start


Descrip
(Variable) Contains the starting offset of the near heap.

Syntax
#include <memalloc.h>
extern unsigned nheap_start;

Notes
This unsigned int variable contains the starting offset of the near heap relative to DGROUP if the near heap is initialized. This variable is undefined if the near heap is not initialized. (If nheap_size is 0, the near heap is not initialized.)

Source file MAVARS.ASM ASM equiv NHEAP_START

_rel_avail


Descrip
Returns the number of available bytes on a relative heap.

Syntax
#include <memalloc.h>
unsigned int _rel_avail(segaddr heapseg);

Returns
The number of bytes available on the relative heap at heapseg.

0 if the relative heap is full or if heapseg is invalid.

Notes
This function returns the total number of available bytes on the relative heap at heapseg. heapseg must be the segment address of a relative heap which was previously initialized using _rel_init. The return value is 0 if the relative heap is full or if heapseg is invalid.

WARNING! Only limited checking is performed to detect an invalid heapseg. If heapseg is invalid, a non-zero value may be returned.

C/C++ Example
	{
	   segaddr heapseg;
	   unsigned int heapsize, heapleft;
	   ...
	   _rel_init (heapseg, heapsize);
	   heapleft = _rel_avail (heapseg);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize;
	   ...
	   mov es,heapseg/* ES = segment for rel heap */
	   mov ax,heapsize/* AX = size of rel heap */
	   rel_init ();	/* initialize relative heap */
	   rel_avail ();	/* AX = bytes avail on heap */
	   ...
	}

Source file _MARAVAL.ASM ASM equiv REL_AVAIL
See also
_far_avail, _near_avail, _rel_init, _rel_max

_rel_calloc


Descrip
Allocates space for a specified number of objects on a relative heap and sets all allocated bytes to zero.

Syntax
#include <memalloc.h>
void far *_rel_calloc(segaddr heapseg, int num, int size);

Returns
A pointer to the allocated block on the relative heap if a block of num times size bytes was successfully allocated.

NULL if num times size bytes could not be allocated.

Notes
This function allocates a word-aligned block on the relative heap at heapseg and returns a pointer to that block. The newly allocated block is num times size bytes in size; a maximum of 32,764 bytes may be allocated in one block. Each allocated byte is cleared to zero. heapseg must be the segment address of a relative heap which was previously initialized using _rel_init. NULL is returned if num times size bytes cannot be allocated or if heapseg is invalid.

WARNING! Only limited checking is performed to detect an invalid heapseg. If heapseg is invalid and NULL is not returned, system memory is left in an undefined state.

WARNING! If num or size is zero, a valid block pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block will corrupt the heap.

C/C++ Example
	{
	   void far *buffer;
	   segaddr heapseg;
	   unsigned int heapsize;
	   ...
	   _rel_init (heapseg, heapsize);
	   /* allocate memory for one window */
	   buffer = _rel_calloc (heapseg, 1, sizeof(sawin));
	   if (buffer == NULL)
	   {
	      /* Handle the error */
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize, size = sizeof(sawin);
	      ...
	   mov es,heapseg
	   mov ax,heapsize
	   rel_init ();
	   mov ax,size
	   mov cx,1
	   rel_calloc ();	/* DI -> allocated block */
	    jc label_010/* if unable to allocate block */
	   ...
	label_010:
	}

Source file _MARCALC.ASM ASM equiv REL_CALLOC
See also
_far_calloc, _near_calloc, _rel_free, _rel_init, _rel_malloc, _rel_max, _rel_realloc

_rel_free


Descrip
Frees a block on a relative heap.

Syntax
#include <memalloc.h>
int _rel_free (void far *block);

Returns
0 if the block was successfully released.

-1 if the function was unsuccessful.

Notes
This function releases the relative heap block at block. This frees the memory for future allocation. block must be the address of a relative heap block which was previously allocated with _rel_malloc, _rel_calloc, or _rel_realloc on a heap that was initialized using _rel_init. 0 is returned if the function was successful. -1 is returned if block is invalid.

WARNING! Only limited checking is performed to detect if block is invalid. If block is invalid and -1 is not returned, system memory is left in an undefined state.

C/C++ Example
	{
	   void far *buffer;
	   segaddr heapseg;
	   ...
	   buffer = _rel_malloc (heapseg, 500);
	   if (buffer == NULL)
	   {
	      /* Handle the error */
	   }
	   ...
	   _rel_free (buffer);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize, bufsize;
	      ...
	   mov es,heapseg/* ES = segment for rel heap */
	   mov ax,heapsize/* AX = size of rel heap */
	   rel_init ();
	   mov ax,bufsize/* AX = size block to allocate */
	   rel_malloc ();	/* DI = offset of block */
	    jc rel_free_010/*   if error allocating block */
	   ... 	 	/*   if successful */
	   rel_free ();	/* free mem block at ES:DI */
	    jc rel_free_010/*   if an error occurred */
	   ... 	 	/*   if successful */
	rel_free_010:
	   }

Source file _MARFREE.ASM ASM equiv REL_FREE
See also
_far_free, _near_free, _rel_calloc, _rel_init, _rel_malloc, _rel_realloc

_rel_init


Descrip
Initializes a relative heap.

Syntax
#include <memalloc.h>
void _rel_init(segaddr heapseg, unsigned int size);

Returns
None

Notes
This function initializes a relative heap. The starting address of the relative heap is heapseg. The size of the relative heap is size bytes. If the relative heap at heapseg was previously initialized, everything which is currently on the heap is discarded.

After initialization, all information about the relative heap is maintained within the heap itself. This allows any number of relative heaps to be defined and it makes each relative heap fully relocatable.

WARNING! This function does not attempt to allocate memory for the relative heap. size bytes of memory must be available at heapseg for use by the relative heap or DOS memory blocks may be corrupted.

C/C++ Example
	{
	   segaddr heapseg;
	   unsigned int heapsize;
	   ...
	   _rel_init (heapseg, heapsize);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize;
	   ...
	   mov es,heapseg/* ES = segment for rel heap */
	   mov ax,heapsize/* AX = size of rel heap */
	   rel_init ();	/* initialize relative heap */
	   ...
	}

Source file _MARNITC.ASM ASM equiv REL_INIT
See also
_near_init, _rel_avail, _rel_malloc

_rel_malloc


Descrip
Allocates a specified number of bytes on a relative heap.

Syntax
#include <memalloc.h>
void far *_rel_malloc(segaddr heapseg, int num);

Returns
A pointer to the allocated block on the relative heap if a block of num bytes was successfully allocated.

NULL if num bytes could not be allocated.

Notes
This function allocates a word-aligned block of num bytes on the relative heap at heapseg and returns a pointer to that block. A maximum of 32,764 bytes may be allocated in one block. heapseg must be the segment address of a relative heap which was previously initialized using _rel_init. NULL is returned if num bytes cannot be allocated or if heapseg is invalid.

WARNING! Only limited checking is performed to detect an invalid heapseg. If heapseg is invalid and NULL is not returned, system memory is left in an undefined state.

WARNING! If num is zero, a valid pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block will corrupt the heap.

C/C++ Example
	{
	   void far *buffer;
	   segaddr heapseg;
	   unsigned int heapsize, bufsize;
	   ...
	   _rel_init (heapseg, heapsize);
	   buffer = _rel_malloc (heapseg, bufsize);
	   if (buffer == NULL)
	   {
	      /* Handle the error */
	   }
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize, bufsize;
	   ...
	   mov es,heapseg/* ES = segment for rel heap */
	   mov ax,heapsize/* AX = size of rel heap */
	   rel_init ();
	   mov ax,bufsize/* AX = size for block */
	   rel_malloc ();	/* DI = offset of block */
	    jc main_010/*   if error allocating block */
	   ... 	 	/*   if successful */
	main_010:
	   ...
	}

Source file _MARMALC.ASM ASM equiv REL_MALLOC
See also
_dos_malloc, _far_malloc, _near_malloc, _rel_calloc, _rel_init, _rel_max, _rel_realloc

_rel_max


Descrip
Returns the size of the largest available block on a relative heap.

Syntax
#include <memalloc.h>
int _rel_max(segaddr heapseg);

Returns
The size of the largest block that can be allocated from the relative heap at heapseg.

0 if the relative heap is full or if heapseg is invalid.

Notes
This function returns the number of bytes in the largest available block on the relative heap at heapseg. heapseg must be the segment address of a relative heap which was previously initialized using _rel_init. 0 is returned if no space is available or heapseg is invalid.

WARNING! Only limited checking is performed to detect an invalid heapseg.

C/C++ Example
	{
	   segaddr heapseg;
	   unsigned int heapsize, heapmax;
	   ...
	   _rel_init (heapseg, heapsize);
	   heapmax = _rel_max (heapseg);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize;
	   ...
	   mov es,heapseg/* ES = segment for rel heap */
	   mov ax,heapsize/* AX = size of rel heap */
	   rel_init ();	/* initialize in real heap */
	   rel_max ();	/* AX = size of block */
	   ...
	}

Source file _MARMAX.ASM ASM equiv REL_MAX
See also
_far_max, _near_max, _rel_avail, _rel_init

_rel_realloc


Descrip
Alters the size of a relative heap memory block.

Syntax
#include <memalloc.h>
void far *_rel_realloc(void far *block, int num);

Returns
A pointer to the resized block if block was successfully resized.

NULL if block could not be resized.

Notes
This function attempts to shrink or grow the relative heap block at block so that it becomes num bytes in size. If the block at block cannot be resized directly, a new block of the requested size is allocated and the contents of the first block are copied into the second block. block must be the address of a relative heap block which was previously allocated with _rel_malloc, _rel_calloc, or _rel_realloc on a heap that was initialized using _rel_init. A maximum of 32,764 bytes may be allocated in one block. A pointer to the resized block is returned if the function was successful. NULL is returned if num bytes cannot be allocated or if block is invalid.

WARNING! Only limited checking is performed to detect if block is invalid. If block is invalid and NULL is not returned, system memory is left in an undefined state.
WARNING! If num is zero, a valid block pointer is returned even though the block has zero bytes of available space. Any attempt to write past the end of a block will corrupt the heap.

C/C++ Example
	{
	   void far *pointer1, far *pointer2;
	   segaddr heapseg;
	   unsigned int heapsize, bufsize, newsize;
	   ...
	   _rel_init (heapseg, heapsize);
	   pointer1 = _rel_malloc (heapseg, bufsize);
	   if (pointer1 == NULL)
	   {
	      /* Handle the error */
	   }
	   ...
	   pointer2 = _rel_realloc (pointer1, newsize);
	   if (pointer2 == NULL)
	   {
	      /* handle the error */
	      pointer2 = pointer1;
	   }
	   ...
	   _rel_free (pointer2);
	}

Inline Assembly Example
	#include <inline.h>
	{
	   segaddr heapseg;
	   unsigned int heapsize, bufsize, newsize;
	   ...
	   mov es,heapseg
	   mov ax,heapsize
	   rel_init ();	/* initialize relative heap */
	   mov ax,bufsize
	   rel_malloc ();	/* DI = offset of block */
	    jc label_020/* if error allocating memory */
	   ...
	   mov ax,newsize
	   rel_realloc ();    /* DI = offset adjusted block */
	    jc label_010/* if unable to expand block */
	   ...
	label_010:
	   rel_free ();
	    jnclabel_020/* if successful */
	   ... 	 	/* if an error occurred */
	label_020:
	   ...
	}

Source file _MARRALC.ASM ASM equiv REL_REALLOC
See also
_far_realloc, _near_realloc, _rel_calloc, _rel_init, _rel_malloc, _rel_max