www.digitalmars.com [Home] [Search] [Contents]

handle.h


handle_calloc

Header

handle.h

Prototype

void __handle *handle_calloc(unsigned size);

Description

The handle_calloc function allocates and clears a block of data, size bytes long, from handle (EMS) memory. If you use this function to allocate handle memory, you must use handle_ functions to manage this memory.

The handle_calloc function returns a __handle pointer that can, with a few restrictions, be used in the same way as any other pointer. A special function, handle_strdup, is provided to make a copy of a string in handle space.

Handle pointers can be used in most situations that a far data pointer could be used. A __handle pointer should be assigned to a normal far pointer before being passed to a formatted print routine. Handle memory cannot currently be used for code.

The use of handle memory can be "locked out" by #defining NO_HANDLE before including handle. h, in which case any use of handle pointers and functions defaults to normal pointers and memory allocation routines.

Note
If handle (EMS) memory is not present in the host system the _handle functions act as if NO_HANDLE is defined. This also occurs when the X, P, or N memory models are used.

Return Value

A __handle pointer to the allocated memory.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

handle_malloc
handle_free
handle_realloc


handle_free

Header

handle.h

Prototype

void handle_free(void __handle *hptr);

Description

The handle_free function frees the memory pointed to by the __handle pointer hptr, that was previously allocated by handle_malloc or handle_calloc.

Return Value

None

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

handle_calloc
handle_malloc

Example
See handle_malloc

handle_ishandle

Header

handle.h

Prototype

int handle_ishandle(void __handle *hptr);

Description

The handle_ishandle function tests whether hptr is a true __handle pointer or a far pointer. If there is no handle memory present, __handle pointers default to being normal pointers.

Return Value

Returns 1 if hptr is a __handle pointer; otherwise returns 0.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

handle_malloc

Example

See handle_malloc 



handle_malloc

Header

handle. h

Prototype

void __handle *handle_malloc(unsigned size);

Description

The handle_malloc function allocates a block of handle (EMS) memory of size bytes from handle space. When you use handle_malloc to allocate handle memory, you must use handle_functions to manage this memory.

The handle_malloc function returns a __handle pointer that can, with a few restrictions, be used in the same way as any other pointer. A special function, handle_strdup, is provided to make a copy of a string in handle space.

Handle pointers can be used in most situations that a far data pointer could be used. A __handle pointer should be assigned to a normal far pointer before being passed to a formatted print routine. Handle memory cannot currently be used for code.

The use of handle memory can be "locked out" by #defining NO_HANDLE before including handle. h, in which case any use of handle pointers and functions defaults to normal pointers and memory allocation routines.

Note
If handle (EMS) memory is not present in the host system the _handle functions act as if NO_HANDLE were defined. This also occurs when the X or P memory models are used.

Return Value

A __handle pointer to the allocated memory.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

handle_calloc
handle_free
handle_malloc

Example

	/* 	Example for handle_malloc */ 

	#include <stdio. h> 
	#include <handle. h>
	#include <stdlib. h>

	/* C and L models ONLY */ 

	void main () 
	{ 
	   char __handle *hptr; 
	   char __handle *cptr; 
	   char *p; 

	   hptr = handle_malloc (256); 
	   if (handle_ishandle (hptr) == 0) 
	      sprintf (hptr, "This string is in normal 
		       memory"); 
	   else 
	      sprintf (hptr, "This string is in handle 
		       memory"); 
	   p = hptr; 
	   printf ("% s -handle pointer is %p\n", p, 
		    hptr); 
	   cptr = handle_strdup (hptr); 
	   p = cptr; 
	   printf ("% s -this time from %p\n", p, cptr); 
	   handle_free (hptr); 
	   handle_free (cptr); 
	   printf ("All Handles freed\n"); 
	} 



handle_realloc

Header

handle. h

Prototype

void __handle *handle_realloc(void __handle
*hptr, unsigned nbytes);

Description

The handle_realloc function reallocates (changes the size of) a block of memory that was allocated by handle_malloc or handle_calloc.

Return Value

A __handle pointer to the reallocated data block.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

handle_calloc
handle_malloc

Example

See handle_malloc 



handle_strdup

Header

handle.h

Prototype

char __handle *handle_strdup(char __handle *hptr);

Description

The handle_strdup function uses handle_malloc to allocate a block of memory in handle space, and then makes a copy of the string pointed to by the __handle pointer hptr in the allocated memory.

Return Value

A __handle pointer to the duplicated string.

Compatibility

DOS Windows 3.x Phar Lap DOSX Win32

See Also

handle_malloc

Example

See handle_malloc